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Preface 


This manual describes the RSX-based utility programs available to RSTS/E 
users. These utility programs are: 


¢e MACRO-11 Assembler Utility Program (MAC) 


The MACRO-11 Assembler processes assembly language programs and sub- 
programs and produces single relocatable binary object files. With the 
MACRO-11 Assembler, you can obtain formatted listings of your source 
(input) code, as well as a symbol table, and table of contents listings. 


e Librarian Utility Program (LBR) 


The Librarian Utility is a library maintenance program that provides a 
means for creating, modifying, updating, listing, extracting, and maintain- 
ing library files. LBR can process both Macro and object module libraries. 


e Object Module Patch Utility Program (PAT) 


With PAT you can modify code in a relocatable binary object (.OBJ) 
Module. 


e Make a Save Image Library Utility Program (MAKSIL) 


MAKSIL Utility program allows you to either create a Save Image Library 
file or a run-time system image file. 


These programs enable you to use the system resources efficiently to create, 
manipulate, and maintain files from a system command level. 


This manual is made up of five chapters. Chapter 1 contains general informa- 
tion on RSTS/E Programmers’s utilities; Chapters 2 through 5 contain de- 
tailed information on use of the MACRO-11 Assembler Utility, the Librarian 
Utility, the Object Module Patch Utility, and the Make a Save Image Library 
Utility. 


You need not read the entire manual to learn the use of a particular utility. 
However, Chapter 1 contains general information that should be read before 
going to the chapter that describes the utility of interest. 
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Documentation Conventions 
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Throughout this manual, symbols and other notational conventions are used 
to represent keyboard characters, and textual information, as well as to clarify 
the presentation of information. The symbols and conventions used are: 


Color 


Uppercase 


Lowercase 


Command 
Abbreviations 


Brackets 
({ ]) 


Commas 


(,) 


At sign 
(@) 


In the dialogue examples used in this manual, colored text 
highlights user response to questions posed by the perti- 
nent program. 


Where uppercase characters appear in a command line for- 
mat, the uppercase characters must be entered as they are 
shown. For example, utility switches are 2-character en- 
tries that must always be entered as they are shown in 
format specifications. 


Lowercase letters, words, or symbols in command line for- 
mat specifications represent variable information. For 
example: 


filnam.ext 


represents a file specification where you substitute alpha- 
numeric information for filnam, and ext. as appropriate. 


Where short forms of commands are allowed (see Section 
1.3.1.2), the shortest form acceptable is represented by 
uppercase letters. This will be determined by the system 
manager. 


Brackets denote optional entries in a specification. Note 
that brackets are a part of the project, programmer num- 
ber in file specifications, that is, [project, programmer]. 
When this portion of a file specification is entered explicit- 
ly, brackets are syntax elements and do not indicate op- 
tional entries. 


Commas are used as separators for command line parame- 
ters. 


The at sign (@) invokes an indirect command file. The at 
sign immediately precedes the file specification for an indi- 
rect command file: 


@dievice:CLCproJect+s Programmer] filnam,.ext 


Periods 


(.) 


Slashes 
(/) 


RET 


"Display" 
and "Type" 


Periods in the file specification separate the filename and 
extension, When the filename is used as the file specifica- 
tion without an ext, the period is not necessary. 


Slashes in the file specification precede switches. When 
shown in format specifications, slashes must be specified 
as they are shown. 


Where a carriage return is used in an example, it is indi- 
cated by the symbol @eD. 


The system "displays" and the user "types". 
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Chapter 1 
Introduction 


This chapter describes the following subjects: 
The RSTS/E command line. 
The RSTS/E file specification. 


The use of utilities and the entering of command lines. 


~~ Oo NH fF 


The conditions under which you can use a utility. 


These subjects are common to all the programmer’s utilities described in this 
manual. 


1.1 RSTS/E Utility Command Line 


The general utility command line format is: 


outfiless...,outfile=infiles...infile 


where outfile and infile are file specifications for the output and input files to 
be operated on by the utility. The number of file specifications you can enter 
depends on the utility invoked, but the maximum length of a command line is 
80 characters. 


This general format varies for each utility. Some utilities use the entire com- 
mand line and others use abbreviated forms of the command line. These 
utilities also accept indirect files containing command lines, as described in 
Section 1.3.2.2. 
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1.2 RSTS/E File Specifications 
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A file specification consists of a filename that conforms to standard RST'S/E 
conventions, plus switches that modify, or specialize, the command. File spec- 
ifications have the form: 


device:LproJect»Pprogrammerlfilename,extensiorn/ Shes. 


where all components are optional except the filename. The file specification 
components are defined below: 


device is the name of the device that stores the file. The device name 
consists of two ASCII characters followed by an optional 1- or 
9-digit decimal unit number; for example, LP or DT1. Logical 
device names of up to six‘alphanumeric characters may also be 
used. 


[project, is the account or project-programmer number (PPN) associ- 
programmer] ated with the file. The default is the PPN of the account you 
have logged into. Note that RSTS/E project-programmer 
numbers are similar to RSX-user identification codes (UIC). 


filename is the name of the desired file. The filename can contain up to 
six alphanumeric characters. 


extension is the 0 to 3-character filename extension. Files having the 
same name but a different function can be distinguished from 
one another by the file extension; for example LRB.TSK and 
LRB.OBJ. 


/sw is a switch specification. More than one switch can be used, 
each separated from the previous one by its slash (/). The 
switch name is a 2- to 4- character alphanumeric code that 
identifies the switch and may also indicate negation of the 
switch. The permissible switches and their syntax are pre- 
sented for each utility in the pertinent chapter. 


Table 1-1 lists the default assumptions for components of a file-specification 
that are not designated. 


Table 1-1: File Specification Defaults 


The device last specified (SY:,if none). 


device 


The project-programmer number last specified (the account you have 
logged into, if there is no previous entry). Any PPN associated with a 
previously specified logical device name does not carry through. 


See Table 1-2. 


project-programmer 


extension 


switch Defaults for each utility described in chapters 2 through 5. 
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Following is an example of input to the MAC Assembler and defaults: 
DKi:IMGi »MPL=INi »DBO:IN2,IN3 


Device File 
DK1: IMG1.0BJ 
DK1: MP1.LST 
SY: IN1.MAC 
DBO: IN2.MAC 
DBO: IN3.MAC 


Table 1-2 lists the default assumptions for missing extensions. 


Table 1-2: File Extension Defaults 


Utility File Type File Description 


MACRO-11 | Input Indirect Command File 
(MAC) Macro Module 
Macro Module Library 
Output Object Module 
List File 


Input Indirect Command File 
Input or Output |. | Object Module 

Input or Output Macro Source Module 
Input or Output ; Object Library Module 
Input or Output ; Macro Module Library 
Output List File 


Patch Input ; Indirect Command File 
(PAT) . Object Module 
Output Object Module 


MAKSIL Input Task Image 
Symbol Table File 
| Indirect Command File 


Resident Library File 
Run-Time System File 
Indirect Command File 


1.3 Accessing Utilities and Entering Command Lines 


The RSTS/E user can access an RSX utility in two ways; and after invoking a 
specific utility, the user then has two choices for entering command lines. The 
paragraphs that follow describe the methods of accessing utilities and enter- 
ing command lines respectively. 


1.3.1 Accessing Utilities 
The two ways to invoke a utility are: 


1. Type the RUN command. 
2. Type a CCL command. 
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The paragraphs below describe each method. 


1.3.1.1 Entering the RUN Command — In response to the system READY 
prompt, you can enter the general form of the RUN command: 


RUN $utility (Qe 


where utility is one of the following: 


MAC.TSK —- MACRO-11 Assembler Utility 
LBR.TSK — Librarian Utility 
PAT. TSK - Patch Object Module Utility 


MAKSIL.BAC - MAKSIL Utility 
For example, you can invoke the Librarian utility by typing the following: 


RUN $LBR, TSK QED 


This prompt is displayed on the terminal ts indicate the Librarian utility is 
ready to accept a command line: 


LBR? 


Note that the use of the symbol $ indicates that the utility is stored in account 
[1,2]. The system manager has the option of installing these utilities in other 
accounts. Check with the system manager for the location of these utilities. 


1.3.1.2 CCL Command Names — If the system manager has installed CCL 
commands for the programmer’s utilities, you can invoke these utilities by 


using the appropriate CCL command. Table 1-3 lists a recommended set of 
CCL names for the RSX utilities invoked by RSTS/E. 


Table 1-3: Conventional CCL Names for RSTS/E Accessed RSX-Based 
Utilities 


COL. Name 


MACRO-11 MAC 


Librarian LBR 
Patch Object Module PAT 
Make Save Image Library MAKSIL 


As an example, you can invoke the PAT utility by typing: 


PAT RED 


The utility indicates its readiness to accept a command line by displaying the 
following prompt: 


PAT = 
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Alternatively, you can employ the following general form of the CCL com- 
mand: | 


PAT ¢gcommand-line > RED 


This form causes the Patch utility to run, process <command-line>, and 
return to the READY state. 


1.3.2 Entering Command Lines 
The two methods for entering utility command lines are: 


1. Typing the complete utility command line. 


2. Using an indirect command. 


1.3.2.1. Entering the Complete Command Lines — You can enter the required 
command line either in response to a utility’s prompt for input or as part of 
the CCL command. Three examples of this method are: 


1. You can employ the RUN command to invoke the utility. The utility 
prompts for command line input. After execution is completed, the utility 
reprompts for additional command input; for example: 


RUN $LBR QED 
LBR:=BIGLIB/IN=SMALL +MID +BIGQ@ED 


LBR = 


2. You can invoke the utility by typing its CCL name. The utility prompts 
for the command line. After execution is completed, the utility reprompts 
for additional command input; for example: 


L BR QED) 
LBR?BIGLIB/IN=SMALL +MID +B1 GED 
LBR > 


3. You can invoke the utility by typing its CCL name followed by a space 
and the complete utility command line. After execution of the utility, the 
system again displays the READY prompt; for example: 


LBR BIGLIB/IN=SMALL +MID +BIGQRED 
READY 


1.3.2.2 Using Indirect Command — The second method of entering a utility 
command line is through the use of indirect command files. When you specify 
an indirect command file, the utility interprets the contents of the file in the 
command specified as a series of one or more command lines. The advantage 
of an indirect command file is that you can enter a commonly used command 
line sequence once and store it for subsequent use rather than reentering the 
sequence. 


The @ character is the first character of the indirect command line. Immedi- 
ately following the @ character is a file specification. The format for an indi- 
rect command is: 
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@device:CrProJjectryprogrammer] filename.extension 


You can omit certain elements of the file specification. The following defaults 
are then applied: 


device - SY: 
[project,programmer] - Current PPN 
extension - .CMD 


The following examples show the use of indirect commands. 


Example 1. 


RUN #LBIR (RET 
LBR>@ALPHA 
LBR > 


Example 2. 


LBR @BETA.CTL 
READY 


In the first example, only the filename, ALPHA is specified. The device, 
account, and extension fields are defaulted. In the second example, a filename 
and extension are specified with the device and account defaulted. 


NOTE 
Indirect command files are not used by MAKSIL 
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Chapter 2 
Using the MACRO-11 Utility Program 


The RSTS/E MACRO-11 utility assembles one or more ASCII source files 
containing MACRO-11 assembly language statements into a single relocata- 
ble binary object file. The output of a MACRO-11 assembly process can 
consist of the following files: 


1. Binary relocatable object file. 
2. Listing file with: 
a. Table of Contents listing, 
b. Source (input) program listing. 


c. Symbol table listing, 


You determine the desired output files to be created during assembly by 

specifying them in the MACRO-11 command line, as described in Section 2.2. 

A set of switches, as described in Section 2.4, allows you to control the exact 
_ form and content of each output file. 


The topics covered in this chapter are: 


Invoking MACRO-11, 
Command Line format. 
File specification, 


Switches. 


oe Se i 


Error messages, 
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2.1 


Invoking MACRO-11 


Chapter 1 describes how you use the RUN and CCL commands to invoke the 
MACRO-11 utility. As a review, calling MACRO-11 by RUN and CCL re- 
spectively is done by entering: 


RUN MAC 


or 

MAC (QED 

and the utility prompts: 
MAC = 


2.2 MACRO-11 Command Line Format. 
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In response to the prompt MAC> displayed by MACRO-11, type the output 
and input file specifications in this form: 


MACtobJectrlisting=srelsesrcof2re.ee 9 SrON 


where: 


object The specification for the binary relocatable object (output) file. 


listing The specification for the assembly listing (output) file that con- 
tains the table of contents, the assembly listing, and the symbol 
table. 


= separates output file specifications from input file specifications. 


srcl, The specifications for the ASCII source (input) files containing the 
scr2,... MACRO-11 source program or the user-supplied macro library 
srcn files to be assembled. 


MACRO-11 recognizes two output file specifications in the command line 
(object and listing). No limit is set on the number of source input files. 
However, a single command line cannot exceed 80-characters including 
spaces. 


The absence of an output file specification in either field means that an 
output file is not produced; for example: 


MAC? »LIST=SORC1+SGRC2 GED 


In this case a binary relocatable object output file is not produced and output 
is a list file (LIST.LST) only. Note that the comma before LIST must be 
included. However, the absence of an input file field is an error condition and 
results in the error message "MAC -- ILLEGAL FILENAME" to be displayed 
at the user terminal (see Section 2.5). 


NOTE 


When a listing file is not specified, any errors encountered in 
the source program are displayed at the user terminal from 
which MACRO-11 was initiated. When the /NL (no list) switch 
is used without an argument in the listing file specification, the 
errors and symbol table are output to the specified file. 
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2.3 MACRO-11 Input/Output File Specification Format 


The file specification serves to define the object files, listing files and source 
files appearing in a MACRO-11 command line. 


The format of the file specification is: 


device: Crprojecty» programmer] filename.extension 


where: 


device: is the name of the device where the desired file 
resides. A device name consists of either two charac- 
ters followed by a 1- or 2-digit decimal unit number, 
and a colon, for example; DP1:, DKO:, DT3:, or a1 to 
6 character logical device name. The default device is 
as specified in Table 1-1. 


[project, programmer] is the project-programmer identification number 
(PPN) associated with the file. The default is the 
PPN logged into. 


filename is the name of the desired file. The filename can con- 
7 tain up to six alphanumeric characters. 


extension is an Q-to-three character alphanumeric filename 
extension. An extension is usually used to identify the 
function of the file. 


2.4 MACRO-11 Switches 


You can append one or more switches to file specifications to modify the 
assembly process. At assembly time, you may want to override certain 
MACRO-11 directives appearing in the source program or to provide 
MACRO-11 with information establishing how certain files are to be pro- 
cessed during assembly. You can do so through one or more switches, which 
may be selectively invoked as additional parameters in each file specification 
(see Section 2.3). Switches are appended to the pertinent file specification, 
without spaces. Also, there are no spaces as a separator. The available 
switches for use in MACRO-11 file specifications under RSTS/E are listed in 
Table 2-1, and associated arguments (:arg) are listed in Table 2-2. 


2.4.1 Listing Control Switches 


There are two listing control options: /LI:arg (list) and /NL:arg (no list). 
These options permit you to override the .NLIST and .LIST directives, 
respectively, in the source code. With these switches you can control the 
content and format of assembly listings. Table 2-2 lists and describes the 
listing control switch arguments. 
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Table 2-1: MACRO-11 Switches 


Controls listing, overrides source program directive .NLIST. 
Controls listing, overrides source program directive .LIST. 


Enables object file function, overrides source program directive 
-.DSABL. 


Disables object file function specified by arg, overrides source 
program directive .KNABLE. (See Table 2-3.) 


Indicates input file is MACRO library file. 


Assemble the specified file during assembly pass 1 only. Assem- 


bly pass 1 locates and reads all requested macros from libraries, 
builds symbol tables and program section tables for the pro- 
gram, and performs a rudimentary assembly of each source 
statement. The use of the /PA:1 switch avoids redefinition of 
MACROSs during pass 2. 


Assemble the specified file during assembly pass 2 only. Assem- 
bly pass 2 creates an object file. This assembly consists of the 
same steps as performed in assembly pass 1, except all source 
statements containing MACRO-11-detected errors are flagged 
with an error code as the assembly listing file is created. The 
object file created contains all the object records, together with 
relocation records having information necessary for subsequent 
Task Builder linking of the object file. 


Table 2-2: Valid Arguments for /LI and /NL Switches 


Controls Listing of | 


List Binary extensions. 
| List | Generated binary code. 
| List | Unsatisfied conditionals, .IF and .ENDC statements. » 
List Comments. 
No List List control directives with no arguments. 
List Address location counter. 
List Macro calls, repeat range expansion. 
List Macro definitions, repeat range expansion. 
No list Macro expansion. 


No list Macro expansion binary code. 


List Source line sequence number. 


List Source Code. 
List Symbol Table. 
List Table of Contents. 


No List 132-column line printer format when not specified. 
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2.4.2 Function Control Switches 


The function control switches (/DS:arg and /EN:arg) allow you to override 
ENABL and DSABL directives in the source code.Table 2-3 lists and de- 
scribes the function control switch arguments. 


Table 2-3: Valid Arguments for /DS and /EN Switches 


Disable 
Disable 
Disable 
Disable 
Disable 
Disable 
Disable 
Enable 
Enable 


Absolute binary output. 


Assembly of all absolute addresses as relative addresses. 


Source columns from 73 on are reserved for comments. 


Floating point truncation. 


Undefined symbols treated as globals. 


Lower case ASCII input. 
Local symbol block. 


Binary output. 


Mnemonic definitions of registers. If REG is not used, the 
definitions listed below remain in effect: 


RO=%00 
R1=%el 
R2=%2 
R3=%s 
R4=%04 
R5=%05 
SP=%6 
PC=%7 


Use of either the function control or listing control options and arguments at 
assembly-time will override any corresponding listing or function control 
directives and arguments in the source program. For example, assume the 
following appears in the source program: 


.NLIST MEB 


¢ 


“(MACRO References) 


»LIST MEB 


In this example, you disable the listing of macro expansion binary code 
(MEB) for some portion of the subprogram and subsequently resume MEB 
listing. However, if you indicate /LI:MEB in the assembly command string, 
the system ignores both the .NLIST MEB and the .LIST MEB directives. 
This enables MEB listing throughout the program. 


The PDP-11 MACRO-1I1 Language Reference Manual contains more detailed 
information on the arguments for both the listing control and function control 
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options. The material is presented in the context of arguments for the assem- 
bler directives .LIST and .NLIST, .ENABL and .DSABL. 


2.4.3 Assembly Pass Switch 


The /PA:arg option is meaningful only if appended to a source input file 
specification. You must specify either /PA:1 or /PA:2. 


The specification /PA:1 calls for assembly of the file during pass 1 only. Some 
files consist entirely of code that is completely assembled at the end of pass 1 
such as a definition file. By specifying /PA:1 for these files, you can cause 
MACRO to skip processing of these files through pass 2. In some cases, this 
procedure can save considerable assembly time. 


The specification /PA:2 calls for assembly of the file during pass 2 only. 
Situations where the /PA:2 option can be meaningfully employed are unusual. 


2.4.4 MACRO Library File Switch 


The /ML option is meaningful only if appended to a source file specification. — 
It has no arguments, and it designates its associated source file as a macro 
library. 


When the assembler encounters an .MCALL directive in the source code, it 
searches macro libraries according to their order of appearance in the com- 
mand line. When it locates a macro whose name matches that given in the 
.MCALL, it assembles the macro as indicated by that definition. If two or 
more macro libraries contain definitions of the same macro name, the macro 
library that appears leftmost in the command line takes precedence. 


Consider the following command line: 


MAC#(output file specification)=ALIB.MLB/ML»BLIB«MLB/ML +xXI2 GED 


Assume that each of the two macro libraries, ALIB and BLIB, contain a 
macro called .BIG, but with different definitions. If source file XIZ contains a 
macro call .MCALL .BIG, the system includes the definition of .BIG in the 
program as it appears in the macro library ALIB. 


NOTE 


A user macro library file with /ML switch must be specified in 
the command line prior to the source files that require it, in 
order to resolve macro definitions. For example: 


output file=ineput file/MLeinput filel»s input file2 


2.5 MACRO-11 Error Messages 
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MACRO-11 produces two types of error indications: a single-letter error code 
(see Appendix A) and a descriptive error message. The single-letter error code 
indicates diagnostic errors produced during assembly and appears on assem- 
bly listings. 
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All of the following error messages, with the exception of the "MAC -—- COM- 
MAND I/O ERROR" message, result in the termination of the current assem- 
bly. MACRO-11 attempts to restart by reading another command line. In the 
case of a command I/O error, however, MACRO-11 exits, since it is unable to 
obtain additional command line input. 


MAC -- COMMAND FILE OPEN FAILURE 


Description: Either the file from which MACRO-11 is reading a command 
could not be opened initially or between assemblies; or, the indirect command 
file specified as "@filename" in the MACRO-11 command line could not be 
opened. See "OPEN FAILURE ON INPUT FILE" for meaning. 


Suggested User Response: Make sure the command file exists and that you 
have read access to the file. Check spelling errors in your command line. 


MAC -- COMMAND I/0 ERROR 


Description: An error was returned by the file system during MACRO-11’s 
attempt to read a command line. This is a fatal error and causes MACRO-11 
to exit. Do not attempt a MACRO-11 restart when this error occurs. 


Suggested User Response: Check command file for correct contents. If this 
occurs with an indirect command file, it indicates that a file contains a bad 
disk block. 


MAC -- COMMAND SYNTAX ERROR 


Description: An error was detected in the syntax of the MACRO-11 command 
line. | 


Suggested User Response: Check command line for spelling errors. Make sure 
you have specified an input file. Check all option switches for correct spelling 
and correct arguments. 


MAC -- ILLEGAL FILENAME 


Description: Neither the device name nor the filename was present in the 
input file specification or a "wildcard" character (asterisk) was employed in an 
input or output file specification. The "wildcard" characters (?) and (*) are 
not permitted in MACRO-11 file specifications. 


Suggested User Response: Check for spelling errors in the command line. 
Check filename specifications for proper format. 


MAC -- ILLEGAL SWITCH 


Description: An illegal switch was specified for a file, an illegal value was 
specified with a switch, or an invalid use of a switch was detected by 
MACRO-11. 


Suggested User Response: Check for spelling errors. Make sure all switch 
arguments are legal for all switches specified. 


MAC -- INDIRECT COMMAND SYNTAX ERROR 
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Description: The name of the indirect command file (@filename) specified in 
the MACRO-11 command line is syntactically incorrect. 


Suggested User Response: Check for spelling errors. Make sure there are no 
wildcards in your file specification. 


MAC -- INDIRECT FILE DEPTH EXCEEDED 


Description: An attempt to exceed the maximum allowable number of nested 
indirect command files has occurred. (Only three levels of indirect command 
files are permitted in MACRO-11.) 


Suggested User Response: Check nesting of indirect command files. Restruc- 
ture the command files so they are not nested to more than three levels. 


MAC -- INVALID FORMAT IN MACRO LIBRARY 


Description: The library file is corrupted or it was not produced by the Librar- 
ian Utility Program (LBR). 


Suggested User Response: Make sure the proper file is being used. If the 
MACRO file is corrupt, rebuild it using LBR. 


MAC -- I/Q ERROR ON INPUT FILE 


Description: In reading a record from a source input file or macro library file, 
an error was detected by the file system. For example, a line containing more 
than 132 characters was encountered. This message may also indicate that a 
device problem exists or a source file or a macro library is corrupted. 


Suggested User Response: Make sure all input lines do not exceed 132 charac- 
ters. Check input file specifications for errors. 


MAC -- 1/0 ERROR ON MACRO LIBRARY FILE 


Description: Same meaning as I/O ERROR ON INPUT FILE, except that the 
file is a macro library file and not a source input file. 


Suggested User Response: Make sure the library file has the correct format 
and has not been corrupted. Check all library file specifications. 


MAC -- I/0 ERROR ON OUTPUT FILE 


Description: In writing a record to the object output file or the listing output 
file, an error was detected by the file system. This message may also indicate 
that a device problem exists or that the storage space on a device has been 
filled. 


Suggested User Response: Insure that there is sufficient space on the output 
media; that the output media is online and ready; and that the device is not 
write locked. 


MAC -- I/0 ERROR ON WORK FILE 


Description: A read or write error occurred on the work file used to store the 
symbol table. Generally, this error is caused by a hardware problem on the 
pertinent device, or by writing to a device that is full. 
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Suggested User Response: See the response for 1/0 ERROR ON OUTPUT 
FILE. 


MAC -- OPEN FAILURE ON INPUT FILE 


Description: This error is caused by one of the following conditions: 


Specified device does not exist. 
The volume is not mounted. 
A problem exists with the device. 


1 
2 
3 
4. Specified directory does not exist. 
5. Specified file does not exist. 

6 


User does not have access to the file. 


Suggested User Response: Check the six possible error conditions listed above. 
Also check for spelling errors on input file specifications. 


MAC -- OPEN FATLURE ON OUTPUT FILE 


Description: This error is caused by one of the following conditions: 


Specified device does not exist. 
The volume is not mounted. 
A problem exists with the device. 


Specified directory does not exist. 


TR 2 Ne 


The volume is full or the device is write protected. 


Suggested User Response: Check the five possible error conditions listed 
above. Also check for spelling errors on the output file specifications. 


MAC -- G4K STORAGE LIMIT EXCEEDED 


Description: 64K words of work file memory are available to MACRO-11. 
This message indicates that the assembler has generated too many symbols 
(13,000 to 14,000) and it has run out of space. This means either the source 
program is too large, or it contains a condition that leads to excessive size, 
such as a macro expansion that recursively calls itself without a terminating 
condition. 


Suggested User Response: Check for recursive macro expansions. Try to use 
fewer macros. Segment the program and assemble the separate parts, using 
global references. 
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Chapter 3 
Using the Librarian Utility Program (LBR) 


With the Librarian Utility Program, (LBR) you can create, update, modify, 
list, and maintain user-generated object and macro library files. LBR files 
contain two directory tables: an entry point table (EPT) that contains entry 
point names (global symbols), and a module name table (MNT) that contains 
module names. Both the EPT and MNT are alphabetically ordered. 


Object module names are derived from .TITLE directives, while entry point 
names are derived from defined global symbols. Once an entry point is locat- 
ed, its associated module can be directly accessed. 


Macro module names are derived from .MACRO directives; macro entry point 
names are not applicable to library processing. 


Chapter 1 describes how to invoke the LBR utility. This chapter contains 
descriptions of: 


Library Files. 

LBR Command Line. 

LBR Switches. 

Procedures for combining Library Functions. 
LBR Restrictions. 

LBR Error Messages, 
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3.1 Library Files 


The library file consists of a one block (256 word) library header, an entry 
point table (each entry point has one entry point name four words long), and a 
module name table (each entry has one module name four words long). In 
addition, each module has an eight-word header. See Appendix B for detailed 
information on the formats and contents of library files. 


NOTE 


LBR accepts indirect command files (see Section 1.3.2) 


3.2 LBR Command Line 


LBR command lines have the general format: 


outfileLvlistfilejJ=infileilCoinfile2s...sinfilen] 


For a complete description of file specifications, see Section 1.2. As an alter- 
native to the use of file specification, you can use an indirect command file as 
described in Section 1.3.2.2. LBR will not accept nested indirect command 
files. | 


3.3 LBR Switches 


LBR uses switches appended to file specifications to invoke functions. These 
switches are summarized-in Table 3-1. 


Table 3-1: LBR Switches 


Option Name | Switch 
Mnemonic Function 


Compress Compress a library file. 

Create Create a library file. 

Delete Delete a library module and all of its entry points. 
Default Specify the default library file type. 

Delete Global Delete a library module entry point. 


Entry Point Control (include) the entry of entry point elements in the 
| library entry point table. 


Do not include the entry of entry point elements in the 
library entry point table. 


Extract Extract (read) one or more modules from a library file and 
write them into the specified output file. 


Insert Insert a module. 
List List module names. 


List module names and module entry points. 


List module names and full module description. 


Replace Replace a module. 

Do not replace a module. 
Selective Search Set selective search attribute in module header. 
Squeeze Reduce the size of macro source. 


Do not reduce the size of macro source. 
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3.3.1 Compress Switch (/CO) 


The Compress switch physically deletes all logically deleted records, moves all 
free space to the end of the file, and makes the free space available for new 
library module inserts. In addition, the library table specification may be 
altered for the resulting library. LBR accomplishes this by creating a new file 
that is a compressed copy of the old library file. In this compression process, 
the actual data in the file is compressed; however the physical length of the 
file remains unchanged. The old library file is not deleted after the new file is 
created (see Section 3.3.3). 


The /CO switch can be appended only to the output file specification. The 
format for specifying the Compress switch is: 


outfile/CO:sizezept:zmnt=infile 


where: 


outfile is the file specification for the file that is to become the compressed 
version of the input file. The default extension is .OLB if the input 
file is an object library, or .MLB if the input file is a macro library. 
Outfile must not have the same name as infile. 


/CO is the Compress switch. 


:$1ze is the size of the new library file in 256—word blocks. If omitted, the 
default size is that of the old library file. 


ept is the number of entry point table (EPT) entries to allocate. If the 
value specified is not a multiple of 64, the next highest multiple of 64 
is used. If omitted, the default value is the number of EPT entries in 
the old library file. This parameter is always set to zero for MACRO 
libraries. Maximum number of entries is 4096. 


‘mnt is the number of module name table (MNT) entries to allocate. If 
the value specified is not a multiple of 64, the next highest multiple 
of 64 is used. If omitted, the default value is the number of MNTs in 
the old library file. Maximum number of entries is 4096. 


infile is the file specification of the library file to be compressed. If the 
current default library type is an object library (OBJ) (see Section 
3.3.4), the file extension default is .OLB. If the current default li- 
brary type is a macro library (MAC), the file extension default is 
MLB. 


For example: 


LBROLIBFIL/CO:100.:156.:70.=FILE1.0LB (eD 
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In this example, file FILE1.OLB is compressed, and a new file, LIBFIL.OLB, 
is created with the following attributes: 


size = 100 blocks 
ept 192 entry points 
mnt = 128 module names 


Note that in the above example the numbers for block size, entry points, and 
module names include decimal points; if omitted, the numbers are inter- 
preted as octal values. 


3.3.2 Create Switch (/CR) 


The Create switch allocates a contiguous library file on a direct access device 
such as a disk. It initializes the library file header, the entry point table, and 
the module name table. The /CR switch can be appended only to the output 
file specifier. The format for specifying the Create switch is: 


outfile/CRisizezsertimntitypPre 


where: 

outfile is the file specification for the library file being created. The 
default file extension is .OLB if an object library is being created, 
or .MLB if a macro library is being created. 

/CR is the Create switch. 

:$1Ze is the size of the library file in 256-word blocks. The default size 
is 100 blocks. 

sept is the number of entry point table (EPT) entries to allocate. The 
default value is 512 for object libraries. This parameter is always 
forced to 0 for macro libraries. Maximum number of entries is 
4096. Once a value is specified or defaulted, an error occurs if an 
Insert or Replace operation exceeds the value. 

‘mnt is the number of module name table (MNT) entries to allocate. 


The default value is 256. Maximum number of entries is 4096. 
Once a value is specified or defaulted, an error occurs if an Insert 
operation exceeds the value. 


extension is the file extension of library to be created. Acceptable exten- 
sions are OBJ for object libraries and MAC for macro libraries. 
The default is the last value specified or implied with the /DF 
switch (see Section 3.3.4), or OBJ if /DF has not been specified. 


In the example below: 
LBR>LIBFIL/CR:50:159. GD 
ept, and extension are assigned default values. 


If the values you specify are not multiples of 64, the EPT and MNT are 
automatically expanded to the next disk block boundary. For example: 


LBR®LIBFIL/CR::128.:64.:0BJ=FILE1,FILE2sFILES3 (éD 
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In this example, LBR performs two functions. First, LBR creates the library 
file LIBFIL.OLB in the user’s account on the public structure (SY:). LIBFIL 
has the following attributes: 


size = 100 blocks (default size) 
ept = 128 entry points 

mnt = 64 module names 

type = OBJ 


Secondly, LBR inserts object modules from the input files FILE1.OBJ, 
FILE2.0BJ, and FILE3.OBJ, that reside in the user’s account on the public 
structure (SY:) into the newly created library file. The insert switch is the 
default switch for input files (see Section 3.3.8). 


3.3.3 Delete Switch (/DE) 


The Delete switch logically deletes library modules and their associated entry 
points (global symbols) from a library file. Up to 15 library modules and their 
associated entry points can be deleted with one delete command. 


When LBR begins processing the /DE switch, it displays the following mes- 
sage at the user terminal: 


MODULES DELETED: 


As modules are logically deleted from the library file, the module name is 
displayed at the user terminal. 


If a specified library module is not contained in the library file, a message is 
displayed, and the processing of the current command is terminated. This 
message is as follows: 


LBR -- *FATAL* - NO MODULE NAMED “name" 


The /DE switch can be appended only to the library file specification. 
NOTE 


When LBR deletes a module from a library file, the module is 
not physically removed from the file, but is marked for dele- 
tion. This means that, although the module is no longer acces- 
sible, the file space that the module occupied is not available 
for use, unless the deleted module is the last module inserted. 
To physically remove the module from the file and make the 
freed space available for use, you must use the /CO switch to 
compress the library (see Section 3.3.1). 


The form for specifying the Delete switch is: 


outfile/DE:modulelLCsmodule2:.4+:modulen] 


where: 


outfile is the file specification for the library file. 
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/DE  __ is the Delete switch. 


‘module is the name of the module to be deleted. 
For example: 


LBR=LIBFIL/DE:MOD1:MOD2:MOD3 @eD 
MODULES DELETED: 

MOD1 

MOD2 


MOD3 


In this example, LBR deletes the modules MOD1, MOD2, and MOD3 and 
their associated entry points from the library file SY:LIBFIL.OLB. 


3.3.4 Default Switch (/DF) 


The Default switch specifies the default library file extension. Acceptable 
values are OBJ for object libraries and MAC for macro libraries. When /DF is 
specified without an argument the default value of arg is OBJ. 


Specifying a default value: 


1. Sets the default extension argument for the Create switch (/CR). 


2. Provides an extension default value of .MLB for macro libraries and .OLB 
for object libraries when opening an output (library) file, except in the 
cases of /CO and /CR. When /CO is specified, the default applies to the 
library input file. When /CR is specified, the default extension is .OLB if 
an object library is being created, or .MLB if a macro library is being 
created. The /DF switch only affects the name of the file to be opened; 
thereafter, the library header record information is used to determine the 
type of library file being processed. 


The /DF switch can be issued alone or appended to a library file specification. 
The form for specifying the Default switch is: 


outfile/DFsextensloties. 
or 


/DFsextension 


where: 
outfile is the file specification for the library file. 
/DF is the Default switch. 


extension is OBJ for object library files and MAC for macro library files. 
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When you specify an extension other than OBJ or MAC, the current default 
library extension will be set to object libraries, and the following message 
displayed: 


LBR -- INVALID LIBRARY TYPE SPECIFIED 


Consider the following: 


1. LBR2/DF:MAC @ED 
LBR2=LIBFIL=INFILE 


File LIBFIL.MLB is opened for insertion. 


2. LBR2=/DF:MAC @& 
LBR=LIBFIL/DF:OBJ=INFILE 


File LIBFIL.OLB is opened for insertion. 


3. LBR:=/DF:MAC 
LBR?LIBFIL/CR 


Macro library LIBFIL.MLB is created. 


4. LBR:/DF:mMac 
LBR=LIBFIL/CR::::0BJ 


Object library LIBFIL.OLB is created. 


5. LBR?/DF 
LBR=TEMP/CO=LIBFIL 


LIBFIL.OLB is opened for compression. If LIBFIL.OLB is an object 
library, the file TEMP.OLB is created to receive the compressed output. If 
LIBFIL.OLB is a macro library (a nonstandard use of the extension OLB), 
the file TEMP.MLB is created. 


6. LBR/DF:0BJ | 
LBR>TEMP/CO=LIBFIL.MLB 


Assuming that file LIBFIL.MLB is a macro library, the macro library file 
TEMP.MLB is created to receive the compressed output. 


3.3.5 Delete Global Switch (/DG) 


The Delete Global switch deletes a specified entry point (global symbol) from 
the EPT. Up to 15 entry points may be deleted with one command. This 
command does not affect the object module, which contains the actual symbol 
definition. 


When LBR begins processing the /DG switch, it displays the following mes- 
sage on the user terminal: 


ENTRY POINTS DELETED: 
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As entry points are deleted from the library file, each deleted entry point is 
displayed.on the user terminal. If a specified entry point is not contained in 
the EPT, a message to that effect is displayed on the user terminal, and the 
processing of the current command is terminated: 


LBR -- *FATAL*® - NO ENTRY POINT NAMED "name" 


The /DG switch can only be appended to the library file specification. 
The format for specifying the Delete Global switch is: 


outfile/DG:globaliC:global2@:..s.:aglobalnd 


where: 


outfile is the library file specification. 
/DG is the Delete Global switch. 
global is the name of the entry point to be deleted. 


For example: 


LBR+ LIBFIL/DG:GLOBi:GLOB2:GLOB3 (eD 
ENTRY POINTS DELETED: 

GLOB1 

GLOB2 

GLOB3 


In this example, the entry points GLOB1, GLOB2, and GLOB3 are deleted 
from the library file named SY:LIBFIL.OLB. 


3.3.6 Entry Point Switch (/EP) 


The entry point switch includes or excludes entry point elements in a library 
entry point table. This switch can be specified in three ways: 


/EP Include entry points in the entry point table. 
/-EP Do not include entry points in the entry point table. 
/NOEP Do not include entry points in the entry point table. 


/EP causes all entry points in a module or modules to be entered in the library 
entry point table. 


/-EP or /NOEP provides for a module to be included in a library while exclud- 
ing the entry points in that module from being entered in the library entry 
point table. 


/EP and /-EP can be applied in the same command line. For example, a 
particular input file with /-EP overrides the effect of /EP in the output file. 
/EP is the LBR default; if the switch is not specified, all entry points are 
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entered into the library entry point table. The Entry Point switch has no 
effect on MACRO libraries. The formats for specifying the Entry Point switch 
are: 


outfilel /EP J=infiles..-infilen 
C[C/-EP ] 
[/NOEP] 
or 
outfile=infilel /EP J+..-.infilenfl/EP J 
C/-EP ] C/-EP ] 
C/NOEP] C/NOEP] 
or 
outfilefL/EP J=infiles.s.s.sinfilenC/EP J 
C/-EP ] . C/-EP ] 
[C/NOEP] C/NOEP] 
where: 


outfile is the output file specification. When the entry point switch is ap- 
plied to this file specification, LBR assumes each of the input files 
contains modules for which entry points are to be either included or 
excluded. 


infile is an input file specification. When the Entry Point switch is applied 
to an input file specification, LBR assumes only the input file(s) has 
the entry point to be included or excluded. 


The /-EP switch is used to select modules from a library by name rather than 
entry point. If the switch is appended to an output file spec then it is in effect 
for all input modules. If it is appended to an input file then it affects only that 
file. 


Entry points in an object module are not affected by the Entry Point switch; 
the entry point switch permits you to either include or exclude entries in the 
library entry point table only. 


3.3.7 Extract Switch (/EX) 


The Extract switch reads one or more modules from a library file and writes 
them into a specified output file. If more than one module is extracted, the 
modules are concatenated in the output file. The extract operation has no 
effect on the library file from which the modules are read; that file remains 
intact. Up to eight modules may be specified in one extract operation. 


If no modules are specified on the command line, all modules in the library 
are extracted and concatenated in the output file in alphabetical order. The 
/EX switch may be applied only to input file specifications. The format for 
specifying /EX is: 


outfile=infile/EXLi:modulename:..s-modulenamed 
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where: 


outfile is the file specification for the file into which extracted mod- 
ules are to be stored. If the input modules are object modules, 
the default extension for this file is .OBJ. If the input modules 
are macro definitions, the default extension is .MAC. 


infile specifies the library file from which the modules are to be 
extracted. The default extension for this file is either OLB or 
MLB, depending on the current default library type. 


/EX is the Extract switch. 


modulename is the name of the module to be extracted from the library. 
Consider the following examples: 
LBR?DRIVER=LIBRY/EX:DXDRY:DKDRYs TTDRY 


The object modules DXDRV, DKDRV, and TTDRV are concatenated and 
written into the file DRIVER.OBJ. 


LBR=KB:=LB:TSTMAC.SML/EX:Q10%% (ED 


The macro QIO$$ is displayed at the issuing terminal. 


LBR?TEST.OBS=TEST/EX eq 


All of the modules in the library TEST.OLB are written into the file 
TEST.OBS in alphabetical order. 


3.3.8 Insert Switch (/IN) 


The Insert switch inserts library modules into an existing library file. An LBR 
command line is limited to 80-characters. Each file specified can contain any 
number of concatenated input modules. For MACRO libraries with nested 
macros, only first-level macro definitions are extracted from the input files. 
All text outside the first-level macro definitions is ignored. The /IN switch is 
the default library file option and can be appended only to the library file 
specification. Note that the number of MNTs and EPTs inserted cannot 
exceed the number defined for the file at its creation. 


When you attempt to insert an input module which already exists in the 
library file, the following message is displayed on the initiating terminal: 


?LBR -- #FATAL*® DUPLICATE MODULE NAME "name" IN filename 


Similarly, if you try to insert a module containing an entry point that already 
exists in the EPT, the following message is displayed on the initiating 
terminal: 


?LBR -- *FATAL*® DUPLICATE ENTRY POINT "name" IN filename 
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The format for specifying the Insert switch is: 


outfilel/INJ=infileilerinfile2sr...rinfilen] 


where: 


outfile is the file specification for the library file into which the input mod- 
ules are to be inserted. The default extension depends on the current 
default (see Section 3.3.4). This extension is .OLB if the current 
default is object libraries, and .MLB if the current default is macro 
libraries. 


/IN is the Insert switch. 


infile is the file specification for the input file containing modules to be 
inserted into the library file. The default extension is .OBJ if outfile 
is an object library, and .MAC if outfile is a macro library. 


For example: 


LBR=LIBFIL/IN=FILE1;FILEZ+FILES (eq 


The modules contained in the files FILE1, FILE2 and FILE3, that reside in 
the user’s account on the public structure (SY:), are inserted into the library 
file LIBFIL, which also resides in your account on SY:. The default extension 
for files FILE1, FILE2, and FILE3 is .OBJ if LIBFIL is an object module 
library, and .MAC if LIBFIL is a macro library. 


3.3.9 List Switches (/LI, /LE, /FU) 


The List switches produce a printed listing of the contents of a library file. 
Three switches allow you to select the type of listing desired: 


/LI Produce a listing of the names of all modules in the library file. 


/LE Produce a listing of the names of all modules in the library file and 
their corresponding entry points. 


/FU Produce a listing of the names of all modules in the library file and 
give a full module description for each; that is, size, date of insertion, 
and module-dependent information. 


These switches can be appended only to the output file specification or the list 
file specification. 


The /LI switch is the default value and need not be specified when a listing 
file has been specified or when /LE or /FU is included in the command. 


The format for specifying List switches is: 


infileCslistfilel/switchles] 
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where: 


infile is the file specification for the library file whose content is to be 
listed. 
listfile is the optional listing file specification. If not specified, the list- 


ing is displayed at the user terminal. 


switchles] is the list option or options selected. 


NOTE 


If listfile is specified, its default device and account (PPN) is 
the same for the library file. Specify SY: if the listfile is on the 
public structure, and specify your own account for listfile if the 
library file is not on your account. 


For example: 


1. LBR? LIBFIL/LI 


In this example, a listing of the names of all the modules contained in file 
SY:LIBFIL.OLB is displayed on the user terminal. 


2. LBR> LIBFIL/LE 


In this example, a listing of the names of all the modules and their entry 
points (contained in file SY:LIBFIL.OLB) is displayed on the user term1- 
nal. 


3. LBR> LIBFIL/FU 


In this example, a listing of the names of all the modules, and a full 
description of each module contained in file SY: LIBFIL.OLB, is displayed 
on the user terminal. | 


4. LBR? DK1i:C200,200]LIBFIL+LP:/LE/FU 


In this example, a listing of the names of all the modules, their entry 
points, and a full description of each module for file LIBFIL, residing in 
directory [200,200] on DK1:, is printed on the line printer. 


3.3.10 Replace Switch (/RP) 


The Replace switch replaces modules in an existing library file with input 
modules of the same name. Note that the number of EPTs placed into the file 
cannot exceed the number defined for the file at its creation. In addition, each 
input file can contain any number of concatenated input modules. 


When a match occurs on a module name, the existing module is marked for 
deletion, and all of its entries are removed from the EPT. If there is also an 
entry point name match, the condition is fatal and terminates the current 
command with an error message (see Section 3.6.2). 
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As each module in the library file is replaced, a message is displayed on the 
user terminal. This message contains the name of the module being replaced: 


MODULE "name" REPLACED 


If the module to be replaced does not exist in the library file, LBR assumes 
that the input module is to be inserted and automatically inserts it without 
displaying a message. 


The /RP switch can be specified in either of the following ways: 


1. Global - The /RP switch is appended to the library file specification, and 
all of the input files are assumed to contain modules to be replaced. 


2. Local - The /RP switch is appended to an input file specification, and only 
the file to which the /RP switch is appended is considered to contain 
modules to be replaced. 


Global Format: 


outfile/RP=infilellCeoinfile2s.+.sinfilen] 


where: 


outfile is the file specification for the library file. The default extension 
depends on the current default (see Section 3.3.4). If the current 
default is object libraries, the extention is .OLB and if the current 
default is macro libraries, the extension is .MLB. | 


/RP is the Replace switch. 


infile is the input file specification for the file that contains modules to be 
replaced in the library file. The default type is .OBJ if outfile is an 
object library, or .MAC if it is a macro library. 


The global format of the /RP switch allows you to specify a list of input files 
without having to append the /RP switch to each of the specifications. To 
override the global function for a particular input file you must instruct LBR 
to process a particular file in a list as a file containing modules to be inserted 
but not replaced, * appending /-RP or /NORP to the desired input file 
specification. 


Local Format: 


outfile=infilel/RPCsinfile2/RPs...sinfilen/RP] 
where: 


outfile is the file specification for the library file. The local format default is 
the same as the global format default described above. 


infile is the input file specification for the file that contains modules to be 
inserted or replaced in the output library file. The local format de- 
fault is the same as the global format default described above. 
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/RP is the Replace switch, and when appended to an input file specifica- 
tion, constitutes the local format of the switch. This overrides the 
LBR default (Insert) and instructs LBR to treat the modules con- 
tained in the specified file as modules to be replaced. 


The files used in the following four examples, and the modules contained 
within each file, are listed in Table 3-2. For the examples, the pertinent files 
are assumed to reside in the default directory on the default device, and the 
initial state of the library file is assumed to be as listed in Table 3-2. 


Table 3-2: Sample Files Used in LBR Examples 


Output 
Library File Input Files 


File Name | LIBFIL.OLB | FILEA.OBJ | FILED.OBJ | FILEB.OBJ | FILEC.OBJ 


FILEC1 
FILED2 


In this example, the global format for the /RP switch is used. Object 
modules from the input files FILEA, FILEB, and FILEC replace modules 
by the same names in the library file named LIBFIL. The resulting library 
file is shown in Table 3-3. 


FILEC1 FILED1 FILEB1 
Object FILEC2 FILEB2 FILEC2 

FILEB1 FILEB3 FILEC3 
Modules FILEB2 


FILEA 


1. LBR2LIBFIL/RP=FILEA+FILEB+FILEC 


FILEA 


MODULE "FILEA" REPLACED 

MODULE "FILEBi" REPLACED 
MODULE "FILEB2" REPLACED 
MODULE "FILEC1i" REPLACED 


MODULE "FILEC2" REPLACED 


Table 3-3: Output Library File After Execution of Example 1 


LIBFIL.OLB 


FILEC1 
FILEC2 
FILEC3 


FILEB1 
FILEB2 
FILEB3 
FILEA 
*These modules did not exist on the library file prior to the 

execution of this example, but they did exist on the input 

files. LBR, therefore, assumed that they were to be insert- 


ed. Since LBR handled these modules as a normal insert, 
no message was printed on the input terminal. 
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2. LBR?® LIBFIL=FILED» FILEA/RP 
MODULE “FILEA" REPLACED 


In this example, the local format of the /RP switch is used. The object 
module FILEA from file FILEA is replaced in the library file LIBFIL. The 
object modules in the file FILED are inserted in the library file. (See 
Section 3.4.8.) The resulting library file is shown in Table 3-4. 


Table 3-4: Output Library File After Execution of Example 2 
| LIBFIL.OLB 


FILED1 
FILED2 
FILEC1 


FILEC2 


FILEB1 
FILEB2 
FILEA 


*This module replaced 


**These modules inserted 


3. LBR> LIBFIL/RP=FILEA»FILEB+FILEC»FILED/-RP 


MODULE "FILEA" REPLACED 

MODULE "FILEB1" REPLACED 
MODULE "FILEB2" REPLACED 
MODULE "FILEC1" REPLACED 


MODULE "FILEC2" REPLACED 


In this example, the /-RP switch is used to override the global format of 
the command. Object modules in files FILEA, FILEB, and FILEC are 
processed as modules to be replaced, and file FILED is processed as a file 
which contains modules to be inserted. The resulting library file is shown 
in Table 3-5. 


4. LBR> LIBFIL/RP=FILEA+FILEB/-RP>»FILEC Ge 


MODULE "FILEA" REPLACED 
?LBR -- *FATAL*® -- DUPLICATE MODULE "FILEBi IN FILEB.OBJ 


In this example, only module FILEA from file FILEA was replaced. The 
user specified that the modules in file FILEB not be replaced (/-RP), but 
inserted. One of the modules contained in file FILEB duplicated an al- 
ready existing module in file LIBFIL (see Table 3-2). Therefore, LBR 
issued the fatal error message and terminated the processing of the cur- 
rent command. 
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Table 3-5: Output Library File After Execution of Example 3 


LIBFIL.OLB 


FILED1 


FILED2 
FILEC1 
FILEC2 
FILEC3 
FILEB1 
FILEB2 
FILEB3 
FILEA 


*These modules were inserted by default. 


**T hese modules were specified to be inserted. Had a mod- 
ule of the same name been present, a fatal error message 
would have been issued. See Example 4. 


3.3.11 Selective Search Switch (/SS) 


The Selective Search switch sets the selective search attribute bit in the 
module header of each object module inserted into an object library. The 
switch has no effect when applied to modules being inserted into a macro 
library. The switch may be specified only on input files for insertion or re- 
placement operations, and it affects all modules in the input file to which it is 
applied. 


Object modules with the selective search attribute bit set are given special 
treatment by the Task Builder. Global symbols defined in object modules 
with the selective search attribute are included in the Task Builder’s symbol 
table only if they are previously referenced by other modules. Therefore, only 

_ referenced global symbols will be listed with the module in the Task Builder 
memory allocation file, thereby reducing task build time. The /SS switch 
should be applied to object files whose modules contain only absolute (not 
relocatable) symbol definitions. See the RSTS/E Task Builder Reference 
Manual Appendix C for more information. 


The format for specifying the Selective Search switch is: 


outfilezinfile1l/SSC rinfile2/SS+..+sinfilen/SS] 


where: 


outfile is the file specification for the library file. 
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infile is the file specification for the input file that contains modules to be 
selectively searched. 


/SS is the Selective Search switch. 


3.3.12 Squeeze Switch (/SZ) 


The Squeeze switch reduces the size of macro definitions by eliminating all 
trailing blanks and tabs, blank lines, and comments from MACRO library 
files. This switch has no effect on object libraries. 


The /SZ switch can be specified in a global or local format. 


1. Global format - The /SZ switch is appended to the library file specifica- 
tion, and all of the input files are assumed to contain modules to be 
squeezed. 


2. Local format - The /SZ switch is appended to an input file specifier, and 
only the file to which the /SZ switch is appended is considered to contain 
modules to be squeezed. 


Global Format: 


outfile/SZ=infilelslCrinfile@o.e.s.s sinfilen] 


where: 
outfile is the file specification for the library file. 
/SZ is the Squeeze switch. 


infile is the file specification for the input file that contains modules to be 
squeezed before being inserted into the library file. 


You can use this format of the /SZ switch to specify a list of input files 
without having to append the /SZ switch to each file. 


To override the global squeeze function for a particular input file that is to be 
inserted but not squeezed, append /-SZ or /NOSZ to the desired input file 
specifier. 


Local Format: 
outfile=infilel/SZC sinfile2?/SZs...esinfilen/S7Z7] 


where: 


outfile is the file specification for the library file. 


infile is the file specification for the file that contains modules to be 
squeezed before being inserted into the library file. 


/SZ is the Squeeze switch. 
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LBR uses the following algorithm on each line to be squeezed and inserts the 
resultant line into the library file: 


1. The line is examined for the rightmost semicolon (;). 


2. Ifa semicolon is located, it is deleted, along with all trailing characters in 
the line. 


3. All trailing blanks and tabs in the line are deleted. 


4. If the resulting line is null, nothing is transferred to the library file. 


The /SZ switch scans for semicolons from right to left and deletes text from 
right to left until the first semicolon is encountered. Only the rightmost semi- 
colon and text to its right are deleted. If the line contains a semicolon embed- 
ded in meaningful (non-comment) text and you want comments squeezed, 
code a dummy comment for that line. The /SZ switch uses only this rightmost 
comment during squeeze processing. 


Figure 3-1 illustrates the use of the LBR /SZ switch. A file containing input 
text to be squeezed is illustrated, along with the text actually inserted into the 
library file after the squeeze operation has been completed. 


Figure 3-1: MACRO Listing Before and After Running LBR with /SZ 
Switch 


BEFORE BEING SQUEEZED 


“MACRO MOVSTR RXoRY > ?PLBL 


jeHH - - NOTE : 5 
4 BOTH ARGUMENTS MUST BE REGISTERS 9 
LBL: MOVE (RA) + 9 CRY) + 3MOVE A CHARACTER 
BNE LBL s;CONTINUE UNTIL NULL SEEN 
DEC RY IBACKUP OUTPUT PTR TO 
NULL 


3END OR MOVSTR 
»ENDM 


AFTER BEING SQUEEZED 


“MACRO MOVSTR RX oRY + ?PLBL 


HHH - - NOTE : 
5 BOTH ARGUMENTS MUST BE REGISTERS 
LBL: MOVB (RX)+5 (RY) + 

BNE LBL 

DEC RY 

»ENDM 
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3.4 Combining Library Functions 


You can request two or more library functions in the same command line. The 
only exceptions are that (1) /CO cannot be requested with anything else 
except /LI, /LE, or /FU, and that (2) /CR and /DE cannot be specified in the 
same command line. 


Functions are performed in the following order: 


1. 
2 
3 
4. 
D 
6 


/DF 

/CR or /CO 

/DE 

/DG 

/IN, /RP, /SS, /SZ 


. /LI, /LE, /FU 


For example: 


LBR: FILE/DE:kY2:$A»LP:/LE/FU=MODA +MODY/RP 


Functions are perfomed in order, as: 


1. 
2. 


Delete modules XYZ and $A. 


Insert all modules from MODX and MODY, replacing any duplicates of 
modules in MODY. 


Produce a listing of the resultant library file on the line printer with full 
module descriptions and all entry points. 


3.5 LBR Restrictions 
The following restrictions apply when using LBR: 


i 
2. 
3. 


Limit of 65,536 words per module. 
Limit of 65,536 blocks per library. 


Tables should be allocated to maximum anticipated size. Expanding table 
allocations requires using the /CO switch to copy the entire file. 


Three conditions result in a fatal error when using the /IN switch to insert 
a module into a library: 


a. The name of the inserted module matches the name of a module al- 
ready in the library. This error can be avoided by using the /RP switch 
to replace one module with another module of the same name. 


b. The entry point name of the inserted module matches an entry point 
name of a module in the library. For further information, refer to 
Section 3.3.8. 


c. The library cannot be extended because of the lack of disk space. 
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5. The use of wildcards, such as *.OBJ, where the * indicates all modules 
with extension .OBJ in file specifiers is not allowed. 


6. There must be enough space in the library’s tables for both the modules 
being replaced and their replacements, since the new modules are entered 
before the old modules are marked for deletion. | 


3.6 LBR Error Messages 
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There are two types of LBR error messages: diagnostic and fatal. 


Diagnostic error messages describe an existing condition that requires consid- 
eration, but does not warrant termination of the command. When a hardware 
error is suspected, examine the system error log to determine the device and 
error type. Diagnostic messages are displayed at the user terminal in the 
format: 


%ZLBR -- *DIAG* - message 


Fatal error messages describe a condition that caused LBR to stop processing 
a command. When this occurs, LBR returns to the appropriate command 
level. For example, if the command is entered in response to the CCL 
command, i.e., 


LBR command 


then, LBR issues the fatal error message and exits. If, however, the command 
is entered in response to the LBR prompt, i1.e., 


LBR>command 


LBR issues the fatal error message and reprompts. 


Fatal error messages are displayed at the user terminal in the format: 


7LBR -- *FATAL® - message 


If a fatal error occurs during the processing of an indirect command file, the 
command file is closed, the fatal error message and command line in error are 
displayed on the user terminal, and LBR returns to the appropriate command 
level. 


3.6.1. Effect of Fatal Errors on Library Files 
The status of a library file after fatal errors is: 


1. In general, output errors leave the library in an indeterminate state. 


2. During the deletion process directed by the /DE switch, the library is 
rewritten prior to the display of the individual module-entry-point-deleted 
messages. 
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3. During the replacement process directed by the /RP switch, the library is 
rewritten prior to the display of the individual module-replaced messages. 


4. During the insert process directed by the /IN switch, the library is rewrit- 
ten after the insertion of all modules in each individual input file. 


3.6.2 List of LBR Errors 


The following list of LBR error messages provides a description of the error 
cause along with suggested user responses. 


LBR -- BAD LIBRARY HEADER 


Description: Either the file is not a library file or the file is corrupted. 
Suggested User Response: 


1. If the file is not a library file, reenter the command line with a proper 
library file specified. 


2. Ifthe volume is corrupted, it must be reconstructed before it can be used. 


LBR ~- COMMAND 1/70 ERROR 


Description: One of the following conditions may exist: 


1. A problem with the physical device (e.g., device hung). 


2. The file is corrupted or the format is incorrect (e.g., record length exceeds 
132 bytes). 


Suggested User Response: Reenter the command line, using the correct 
syntax. 


LBR -- COMMAND SYNTAX ERROR 
command line 


Description: A command was entered in a format not conforming to syntax 
rules. 


Suggested User Response: Reenter the command line, using the correct syn- 
tax. 


LBR -- DUPLICATE ENTRY POINT NAME "name" IN filename 


Description: An attempt was made to insert a module into a library file when 
both the insert module and a module in the library file have an identical entry 
point names. 


Suggested User Response: Determine if the specified input file is the correct 
file. If not, reenter the command line, specifying the correct input file. If the 
input file is the correct file, the user may delete the duplicate entry point from 
the library and try again. 
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LBR -- DUPLICATE MODULE NAME "name" IN filename 


Description: An attempt has been made to insert a module into a library that 
already contains a module with the specified name, without use of the /RP 
switch. 


Suggested User Response: Determine if the specified input file is the correct 
file. If the input file is correct, decide whether to delete the duplicate module 
from the library file and insert the new one, or replace the duplicate module 
by rerunning LBR with the /RP switch appended to the input file 
specification. 


LBR -- EPT OR MNT EXCEEDED IN filename 
Description: The EPT or MNT table limit has been reached during the execu- 


tion of an Insert or Replace command. 


Suggested User Response: Copy the library, increasing the table space 
through use of the /CO switch. Reenter the command line. 


LBR -- EPT OR MNT SPACE EXCEEDED IN COMPRESS 


Description: An EPT or MNT table size was specified for the output library 
file that is too small to contain the EPT or MNT entries used in the input 
library file. 


Suggested User Response: Reenter the command line with a larger EPT or 
MNT table size specified. 


LBR -- ERROR IN LIBRARY TABLES: FILE filename 


Description: The library file is corrupted or is not a library file. 


Suggested User Response: If the file is corrupted, no recovery is possible and 
the file must be reconstructed. If the file is not a library file, reenter the 
command line with the correct library file specified. 


LBR -- EXACTLY ONE INPUT FILE MUST APPEAR WITH /CO 

Description: No file or more than one input library file was specified in the 
/CO command. 

Suggested User Response: Reenter the command line with only one input file 
specified. 


LBR -- FATAL COMPRESS ERROR 


Description: The input library file is corrupted or is not a library file. 


Suggested User Response: No recovery is possible. The file in question must 
be reconstructed. 
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LBR -- GET TIME FAILED 
Description: This error occurs when LBR attempts to execute a Get Time 
Parameters directive and fails. The error is caused by a system malfunction. 


Suggested User Response: Reenter the command line. If the problem persists, 
submit a Software Performance Report along with the related console dia- 
logue and any other pertinent information. 


LBR -- ILLEGAL DEYVICE/VOLUME 
command line 


Description: Device specifier entered is not a valid device name. A device 
specifier consists of two ASCII characters, followed by one or two optional 
digits. 


Suggested User Response: Reenter the command line with the correct device 
syntax specified. | 


LBR -- ILLEGAL DIRECTORY 
command line 


Description: The PPN entered does not conform to syntax rules. PPN syntax 
consists of a left square bracket, followed by one to three digits, a comma, one 
to three digits, and terminated by a right square bracket. 


Suggested User Response: Reenter the command line with the correct PPN 
syntax. 


LBR -- ILLEGAL FILENAME 
command line 


Description: One of the following was entered: 


1. A file specification containing a wildcard. 


2. A file specification that neither is a filename nor has an extension. 
Suggested User Response: Reenter the command line correctly. 
LBR -- ILLEGAL GET COMMAND LINE ERROR CODE 


Description: The system, due to an internal failure, is unable to read a com- 
mand line. 


Suggested User Response: Reenter the command line. If the problem persists, 
submit a Software Performance Report along with the related console dia- 
logue and any other pertinent information. 


LBR -- ILLEGAL SWITCH 
command line 


Description: A switch was not recognized or a legal switch was specified in an 
invalid context. 
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Suggested User Response: Reenter the command line with the correct switch 
specification. 


LBR -- ILLEGAL SWITCH COMBINATION 
Description: Switches were entered that cannot be executed in combination. 
See Section 3.4. 


Suggested User Response: Reenter the command line, specifying the switches 
in the proper sequence. 


LBR -- INDIRECT COMMAND SYNTAX ERROR 
command line 


Description: An indirect file was specified in a format that does not conform 
to syntax rules. 


Suggest User Response: Reenter the command line with the correct syntax. 


LBR -- INDIRECT FILE DEPTH EXCEEDED 
command line 


Description: An attempt has been made to exceed one level of indirect com- 
mand files. 


Suggested User Response: Rerun the job with only one level of indirect com- 
mand file. 


LBR -- INDIRECT FILE OPEN FAILURE 
command line 


Description: The requested indirect command file does not exist as specified. 
One of the following conditions may exist: 


The user tried to read a file and was denied access. 
A problem exists on the physical device. 
The volume is not mounted. 


The specified file directory does not exist. 


G2 ae 2 


The specified file does not exist. 


Suggested User Response: Determine which of the above conditions caused 
the message and correct that condition. Reenter the command line. 


LBR -- INPUT ERROR ON filename 


Description: The file system, while attempting to process an input file, has 
detected an error. A problem exists with the physical device due to some 
transient condition. 
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Suggested User Response: Reenter the command line. 

LBR -- INVALID EPT AND/OR MNT SPECIFICATION 

Description: An EPT or MNT value greater than 4096 was entered in a/CR or 
/CO switch. 


Suggested User Response: Reenter the command line with a valid value. 


LBR -- INVALID FORMAT» INPUT FILE filename 
Description: The format of the specified input file is not the standard format 
for a macro source or object file, or the input file is corrupted. 


Suggested User Response: Reenter the command line with the correct input 
file specified. 


LBR -- INVALID LIBRARY TYPE SPECIFIED 


Description: An illegal library extension was specified in a Create (/CR) or 
Default (/DF) command line. The extensions OBJ and MAC are the only 
valid specifications. See Sections 3.3.2 and 3.3.4. 


Suggested User Response: Reenter the command line with OBJ or MAC 
specified. 


LBR -- INVALID NAME -- "name" 
Description: A module name or entry point that contains a character that is 
not in the Radix-50 character set has been specified for deletion. Radix-50 


characters consist of the letters A through Z, the numbers 0 through 9, and the 
special characters period (.) and dollar sign ($). 


Suggested User Response: Reenter the command line with a valid name. 


LBR -- I/O ERROR INPUT FILE filname 


Description: A read error has occurred on an input file. One of the following 
conditions may exist: 


1. A problem exists on the physical device. 


2. The file is corrupted or the format is wrong (record length exceeds 132 


bytes). 


Suggested User Response: Determine which of the above conditions caused 
the message and correct that condition. Reenter that command line. 


LBR -- LIBRARY FILE SPECIFICATION MISSING 


Description: A command was entered without specifying the library file. 


Suggested User Response: Reenter the command line with the library file 
specified. 
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LBR -- MARK FOR DELETE FAILURE ON LBR WORK FILE 
Description: When LBR begins processing commands, it automatically cre- 
ates a work file marked for deletion. For some reason, this operation failed. 


Suggested User Response: Reenter the command line. 


LBR -- MISSING OUTPUT FILE SPECIFIER 
Description: The outfile specification was not included in the LBR command 
line. 


Suggested User Response: Reenter the command line with the outfile specifi- 
cation included. 


LBR -- NO ENTRY POINT NAMED “name” 


Description: The entry point to be deleted is not in the specified library file. 


Suggested User Response: Determine if the entry point is misspelled or if the 
wrong library file is specified. Reenter the command line with the entry point 
correctly specified. 


LBR -- NO MODULE NAMED “module" 


Description: The module to be deleted is not in the specified library file. 


Suggested User Response: Determine if the module name is misspelled or if 
the wrong library file is specified. Reenter the command line with the module 
name correctly specified. 


LBR -- OPEN FAILURE ON FILE filename 


Description: The file system, while attempting to open a file, has detected an 
error. One of the following conditions may exist: 


The user tried to read a file and was denied access. 
A problem exists on the physical device. 


The volume is not mounted. 


1 
2 
3 
4. The specified file directory does not exist. 
5. The specified file does not exist. 

6 


. There is insufficient contiguous space to allocate the library file (this 
applies to the Compress and Create switches only). 


Suggested User Response: Determine which of the above conditions caused 
the message and correct that condition. Reenter that command line. 
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LBR -- OPEN FAILURE ON LBR WORK FILE 


Description: While attempting to open the LBR work file, an error was detect- 
ed. One of the following conditions may exist: 


1. The volume is full. 
2. The device is write-protected. 


3. A problem exists with the physical device. 


Suggested User Response: Determine which of the above conditions caused 
the message and correct that condition. Reenter the command line. 


LBR -- OUTPUT ERROR ON filename 


Description: A write error has occurred on the output file. One of the following 
conditions may exist: 


1. The volume is full. 
2. The device is write-protected. 


3. The hardware has failed. 


Suggested User Response: If the volume is full, delete all unnecessary files and 
rerun LBR. If the device is write-protected, logically dismout write-enable, 
logically remount, then reenter the command line. If the hardware has failed, 
assign a new device and reenter the command line. 


LBR -- TOO MANY INPUT FILES 


Description: Too many input file specifications were included in the LBR 
command line. You are limited to 80 characters. 


Suggested User Response: Reenter a command line not exceeding 80 
characters. 


LBR -- TOO MANY OUTPUT FILES SPECIFIED 


Description: More than two output files were specified; LBR makes the fol- 
lowing assumptions: 


1. The first output file specified is the output library file. 
2. The second output file specified is the listing file. 


Suggested User Response: No action is required. LBR ignores any remaining 
file specifications. 
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LBR -- POSITIONING ERROR ON filename 


Description: The device is write-locked. 
Suggested User Response: If the device is write-locked, logically dismout the 
device, write-enable it, logically remount it, and reenter the command line. 


LBR -- VIRTUAL STORAGE REQUIREMENTS EXCEED 65536 WORDS 


Description: This error may occur with maximum size libraries in conjunction 
with a single command line which logically deletes a large number of modules 
and entry points, and continues to replace them with an equally large number 
of modules and entry points having highly dissimilar names. Normally, this 
message indicates some sort of internal system error. 


Suggested User Response: Rerun the job, but divide the complicated com- 
mand line into several smaller command lines that do the same operations. 


LBR -- WORK FILE I/0 ERROR 


Description: A write error has occurred on the LBR work file. One of the 
following conditions may exist: 


1. The volume is full. 

2. The device is write-protected. 

3. The hardware has failed. 

Suggested User Response: If the volume is full, delete all unnecessary files and 
rerun. If the device is write-protected, logically dismount the device, write 


enable it, logically remount it, and reenter the command line. If the hardware 
has failed, assign a new device and retry the command. 


Using the Librarian Utility Program (LBR) 


Chapter 4 


Using The Object Module Patch  Utlity (PAT) 
Program 


The Object Module Patch Utility Program (PAT) allows you to patch or 
update object code that is in a relocatable binary object module. Although 
PAT can in theory patch any binary object file, in practice it is feasible to use 
PAT to patch only .OBJ files generated by MACRO-11. PAT accepts a file 
containing corrections or additional instructions, and applies these corrections 
or additions to the original object module to produce an updated object mod- 
ule. Figure 4-1 illustrates this procedure. Also, PAT allows you to increase the 


size of object modules since changes are made before the module is linked by 
the Task Builder. 


This chapter covers the following major topics: 
¢ How PAT Works 

e Specifying the PAT Command String 

¢ How PAT Applies Updates 


e PAT Messages 


4.1 How PAT Works 
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PAT receives input from two files: the file being corrected and a correction 
file. The input file consists of one or more object modules in a single file. You 
may correct only one of these object modules with a single execution of PAT. 
The correction file consists of previously assembled object code containing 
corrections and additions to the input file. When linked by the Task Builder, 
the correction file either overlays or is added to the original object module. 
Output from PAT is the updated, or new object file. 


You can invoke PAT using any of the methods for invoking a utility as de- 
scribed in Chapter 1. 


Figure 4-1 shows how PAT updates a file (FILE1) consisting of three object 
modules (MOD1, MOD2, and MOD3) by appending a correction file to 
MOD2. The updated module is then relinked with the rest of the file by the 
Task Builder to produce an executable task. 


Figure 4-1: Updating a Module Using PAT 


PAT 


UPDATE2 


MOD3 


UPDATE2 | 
= | Q-MK-00048-00 


There are several steps involved when using PAT to update a file. First, you 
must create the correction file by using PIP (see RSTS/E System User’s 
Guide) or a text editor. The correction file must then be assembled to produce 
an object module. The input file and the correction file are then submitted to 
PAT for processing. Finally, the updated object module, along with the object 
modules that comprise the rest of the file, can be submitted to the Task 
Builder to resolve global symbols and create an executable task. Figure 4-2 
illustrates the processing steps involved in generating an updated task file 
using PAT. 
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Figure 4-2: Processing Steps Required to Update a Module Using PAT 
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AND GENERATE AN = 
EXCUTABLE TASK. 


NOTE: PREFORM STEP 3 ONLY IF THE ORIGINAL 


MODULE IS ON THE LIBRARY FILE. F-MK-00047-00 
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4.2 Specifying the PAT Command Line 


A PAT command line has the following form: 


CoutfilejJ=infilelL/CSCinumberl] »scorrectfilel/CSCinumberd] 


where: 


outfile 


infile 


correctfile 


/CS 


number 


is the file specification for the output file. Outfile must have a 
different name than the infile. If you do not specify an output 
file, none is generated. 


is the file specification for the input file. This file can contain one 
object module or several concatenated object modules. 


is the file specification for the correction file. This file contains 
the corrections being applied to a single module in the input file. 


specifies the Checksum switch (/CS), which directs PAT to gen- 
erate an octal value for the sum of all the binary data for the 
module in the file to which the switch is applied. (See Section 
4.3.5.) 


specifies an octal value that PAT compares to the computed 
checksum value. 


NOTE 


PAT accepts indirect command files (see Section 1.3.2). 


4.3 How PAT Applies Updates 
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PAT applies updates to a base input module using additions and corrections 
supplied in a correction file. This section describes the format of input and 
correction files, provides information on how to create a correction file, along 
with pertinent examples. 


4.3.1 The Input File 


The input file is the file to be updated, and therefore is the base for the 
updated output file produced. The input file must be in object module format. 
When PAT executes, the correction file module is applied to this file. 
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4.3.2 The Correction File 


The correction file also must be in object module format. It is usually created 
from a MACRO-11 assembler source file in the following format: 


*TITLE inputname 
»IDENT updatenum 
inPputline 
inPutline 

% 


% 
% 


where: 


inputname is the name of the module to be updated by PAT, and must be 
the same as specified in the input file’s .TITLE directive for 
that module. 


updatenum is any value acceptable to the MACRO-11 assembler. General- 
ly, this value identifies the update version of the file being 
processed by PAT, as shown in the examples below. 


inputline is each line of input to be used to correct and update the input 
file. 


During execution, PAT adds the new global symbols defined in the correction 
file to the module’s symbol table. Duplicate global symbols in the correction 
file supersede their counterparts in the input file, provided both definitions 
are either relocatable or absolute. 


A duplicate PSECT or CSECT supersedes the previous PSECT or CSECT, 
provided: 


1. Both have the same relocatability attribute (ABS or REL). 
2. Both are defined with the same directive (.PSECT or .CSECT). 
If PAT encounters duplicate PSECT names, the length attribute for the 


PSECT is set to the length of the longer PSECT and a new PSECT name is 
assigned to the other module. 


If a transfer address is specified, it supersedes that of the module being 
patched. 


4.3.3 Creating the Correction File 


Referring to Figure 4-2, the first step in using PAT to update an object file is 
to generate the correction file. Use any editor program to generate these addi- 
tions and corrections to your file. , 


The correction file must be in object module format before it can be processed 
by PAT. When you have created the source version of the correction file, you 
must have it assembled in order to produce an object module that PAT can 
process. 
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4.3.4 How PAT and the Task Builder Update Object Modules 


The following examples show an input file and a correction file to be processed 
by PAT and Task Builder, along with a source-like representation of the 
output file after PAT and Task Builder complete processing. Programs that 
used the patched object module must be re-task built. Before Task-building, 
corrections and additions are only appended to the patched object module. 
After task-building, the additions and corrections are placed in their proper 
locations in the task image. Two techniques are used in this process; overlay- 
ing lines in a module, and appending a subroutine to a module. 


4.3.4.1 Overlaying Lines in a Module — The example below illustrates a tech- 
nique for overlaying lines in a module using a patch file. First, PAT appends 
the correction file to the input file. The Task Builder is then executed to 
replace code within the input file. The input file for this example is: 


»TITLE ABC 
| »IDENT /O1/ 
ABC 
MOY A rC 5 
CALL AZ j 
RETURN 5 
»END 


To add the instruction ADD A,B after the CALL instruction, include the 
following patch source file: 


*TITLE ABC 
*IDENT /01.Q01/ 

e=,t+1le2 
ADD A+B 5 
RETURN 5 
«END 


The patch source is assembled using MACRO-11, and the resulting object file 
is input to PAT along with the original object file. The updated object module 
appears as follows: 


*TITLE ABC 
*IDENT /01,01/ 
ABC:: 
MOY A»C : 
CALL KYZ 3 
RETURN 3 
»*=ABC 
o=,+12 
ADD A+B 3 
RETURN 9 
«END 
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After Task Builder processes these files, the task image appears as follows: 


»eTITLE ABC 
»eIDENT /01,01/ 

ABC:: 
MOY A;yC 5 
CALL KY2 j 
ADD A+B 5 
RETURN j 
» END 


The Task Builder uses the .=.+12 in the program counter field to determine 
where to begin overlaying instructions in the program. The Task Builder 
overlays the RETURN instruction with the patch code: 


ADD 
RETURN 


A;B 


4.3.4.2 Adding a Subroutine to a Module — This example illustrates a tech- 
nique for adding a subroutine to an object module. In many cases, a patch 
requires that more than a few lines be added to patch the file. A convenient 
technique for adding new code is to append it to the end of the module in the 
form of a subroutine. This way, you can insert a CALL instruction to the 
subroutine at an appropriate location. The CALL directs the program to 
branch to the new code, execute that code, and then return to in-line process- 
ing. The input file for the example is: 


1 *ENABL GBL 
3 
4 *eTITLE ABC 
a) + IDENT 
6 900000 016767 oo0000G O00000G ABC:: MOV A+B 3 
7 O00006 CALL KYE2 3 
0900006 004767 o00000G JSR PC +KY2Z 
B o00012 016700 o0a0000G MOV C »kO 3 
9 O00016 RETURN 5 
O0001G 000207 RTS PC 
10 5 % 
11 5 * 
12 5 % 
13 QQ0001 »END 
The correction file for this example is: 
1 »*ENABL GBL 
3 
4 »>TITLE ABC 
ra) *IDENT /01,01/ 
G6 900000 CALL PATCH 5 
000000 004767 000000G JSR PC »PATCH 
7 000004 o00240 NOP 9 
8 000000 PSECT PATCH j 
9 o00000 PATCH: 
10 900000 016767 000000G 000000G MOY A»B ; 
11 O00006G6 016700 O00000G MOV D»kO j 
i2 Qg00012 006300 ASL RO ; 
13 000014 RETURN 3 
000014 000207 RTS PC 
14 000001 » END 
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PAT appends the correction file to the input file, as in the overlay example. 
The Task Builder then processes the file and the following output file is 


generated: 
1 »*ENABL  GBL 
3 
dj »>TITLE ABC 
ra »*IDENT O17,01/ 
6 200000 ABC:: 
7 OOd000 CALL PATCH 5 
NQO0000 Q004767 dO00000G JSR PC »PATCH 
8B o0000g o007d0 NOP 5 
9 900006 CALL KY 2 j 
QQg0006 004767 QOQQ00G JSR PC skY2 
10 o0o0o0o12 O16700 QIQQ0aQG MOW C,yRO 5 
11 9000016 RETURN j 
QOQQ01G OOOQ207 RTS PC 
12 j % 
13 5 % 
14 5 % 
15 a00000 »>PSECT PATCH 
16 o00000 PATCH: 
17 O0O0000 oO16767 on0000G O00000G MOV A+B 5 
18 090000G 016700 o00000G MOU D>RO 5 
—~=19 Oo00012 QONG6300 ASL RO 5 
20 O00014 RETURN 5 
Q0001d oO00207 RTS PC 
rage ONO0001 + END 


In this example, the CALL PATCH and NOP instructions overlay the three- 
word MOV A,B instruction. The NOP is required because a two-word instruc- 
tion replaces a three-word instruction and NOP is required to maintain word 
boundary alignment. The Task Builder allocates additional storage for 
PSECT PATCH, writes the specified code into this program section. and 
binds the CALL instruction to the first address in this section. Note that the 
MOV A,B instruction replaced by the CALL PATCH is the first instruction 
executed by the PATCH subroutine. 


4.3.5 Determining and Validating the Contents of a File 


The Checksum switch (/CS) validates the contents of a module. The Check- 
sum switch directs PAT to compute the sum of all binary data in a file. If 
specified in the form /CS:number, /CS directs PAT to compute the checksum 
and compare that checksum to the value specified as number. 


To determine the checksum of a file, enter the PAT command line with the 
/CS switch appended to the file specification whose checksum is being deter- 
mined, for example: 


=INFILE/CS »INFILE. PAT@ED 


PAT responds to this command with the message: 


INPUT MODULE CHECKSUM IS <checksum> 
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A similiar message is generated when the checksum for the correction file is 
requested. 


NOTE 


A checksum is an octal number which is the sum of all the eight 
bit binary values, less carries, comprising an object module. 


To validate the changes to a file, enter the Checksum switch in the form 
/CS:number. PAT compares the value it computes for the checksum with the 
value you specify as number. If the two values do not match, PAT displays 
the message: 


ERROR IN FILE <filename>* CHECKSUM 


A checksum is always a nonzero value. 


4.4 PAT Messages 


PAT generates messages that state checksum values and messages that de- 
scribe error conditions. For checksum values and nonfatal error messages, 
PAT prefixes messages with: 


%PAT -- *DIAG - 


For error messages that describe errors causing PAT to terminate, PAT uses 
the prefix: 


PPAT -- #FATAL - 


Fatal and diagnostic errors may still result in the creation of the requested 
output files. All output files created prior to a fatal error should be deleted; all 
diagnostic error output files should be examined and a decision made on 
whether or not to keep them. 


The messages described below are grouped according to message type, as 
follows: 


Information messages. 
Command line errors. 


Input/output errors. 


1 
2 
3 
4. Errors in file contents or format. 
5. Internal software errors. 

6 


Storage allocation errors. 


4.4.1 Information Messages 


The following messages describe results of checksum processing. 
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CORRECTION INPUT FILE CHECKSUM IS «checksum: 


Description: <checksum> is the module checksum displayed in response to 
the /CS switch appended to a correction input file specification. The value is 
printed in octal. 


Suggested User Response: No response necessary. 


INPUT MODULE CHECKSUM IS “checksum? 


Description: <checksum> is the module checksum displayed in response to 
the /CS switch appended to an input file specification. The value is printed in 
octal. 


Suggested User Response: No response necessary. 


4.4.2 Command Line Errors 


The following errors result from failure to adhere to the command !ine syntax 
rules. 


COMMAND LINE ERROR «command line= 


Description: The displayed command line contains an error detected by the 
command line processor. 


Suggested User Response: Reenter the command line using the correct syntax. 
COMMAND SYNTAX ERROR <command line> 

Description: The command line displayed contains a syntax error. 
Suggested User Response: Reenter the command line using the correct syntax. 


ILLEGAL INDIRECT FILE SPECIFICATION «command line= 


Description: The displayed command line contains an indirect file specifica- 
tion that contains one of the following errors: 


e A syntax error in the file specification. 


e Specification of a non-existent indirect file. 


Suggested User Response: Check for file specification syntax errors. Check 
that the specified file is contained in the User File Directory. 


MAXIMUM INDIRECT FILE DEPTH EXCEEDED «command line*® 


Description: The command line displayed specifies an indirect command file 
that exceeds the nesting level (level 2) permitted by PAT. 


Suggested User Response: Reorder your files so that they do not exceed the 
nesting limit. 
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4.4.3 File Specification Errors 


The following messages are caused by errors in the specification of input or 
output files or related file switches. 


CORRECTION INPUT FILE MISSING <command line? 
Description: The command line does not contain the mandatory correction 
file input specification. 


Suggested User Response: Reenter the command line specification including 
the correction file. 


ILLEGAL DEVICE/YOLUME SPECIFIED <device name> 
Description: <device name> does not adhere to the syntax rule for specifying 
device or volume. 


Suggested User Response: Check the rules for specifying the device and 
reenter the command line with the correct device specified. 


ILLEGAL DIRECTORY SPECIFICATION <directory name: 


Description: The directory string displayed does not adhere to the syntax 
rules for specifying directories. 


Suggested User Response: Reenter the command line specifying the directory 
string in the correct syntax. 


ILLEGAL FILE SPECIFICATION «filename: 


Description: The filename printed does not adhere to the syntax rules for file 
specifications. 


Suggested User Response: Reenter the command line using the correct syntax 
for the filename. 


ILLEGAL SWITCH SPECIFIED «filename: 


Description: An unrecognized switch or switch value has been appended to 
the filename displayed. 


Suggested User Response: Check the rules for specifying the switch and 
reenter the command line. 


INVALID FILE SPECIFIED «filename = 


Description: The filename displayed: 


1. References a nonexistent device. 


2. References a nonexistent PPN. 
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Suggested User Response: Correct the device or PPN specification and reenter 
the command line. 


MULTIPLE OUTPUT FILES SPECIFIED “command line+ 


Description: Only one output file specification is accepted by PAT. 


Suggested User Response: Reenter the command line with only one output file 
specified. | 


REQUIRED INPUT FILE MISSING «command line+ 


Description: The command line does not contain the mandatory input file 
specification. 


Suggested User Response: Reenter the command line specification input file. 
TOO MANY INPUT FILES SPECIFIED ¢command line= 


Description: The command line displayed contains too many input file speci- 
fications. PAT accepts one input and one correction file specification. 


Suggested User Response: Reenter the command line specifying the correct 
files. 


SYMBOL --- IS MULTIPLY DEFINED 


Description: Multiple definitions of a symbol has occurred. 


Suggested User Response: Rename one or more of the duplicate symbols, then 
regenerate correction file. 


UNABLE TO FIND FILE <filename? 


Description: The specified input or correction file could not be located. 


Suggested User Response: Ensure that the file exists. Reenter the command 
line. 


4.4.4 Input/Output Errors 


The error messages listed below are caused by faults detected while perform- 
ing I/O to the specified file. 


ERROR DURING CLOSE: FILE: «filenames 


] 
Description: This error is most likely to occur while attempting to write the 
remaining data into the output file before closing it. The principal sources of 
error in these circumstances are: 


1. Device full. 


2. Device write-locked. 
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Suggested User Response: Perform the appropriate corrective action and 
reenter the command line. 


ERROR POSITIONING FILE <filename> 


Description: An attempt has been made to position the file beyond end-of-file. 


Suggested User Response: Submit a Software Performance Report along with 
the related console dialogue and any other pertinent information. 


1/0 ERROR ON INPUT FILE <filename> 


Description: An error was detected while attempting to read the specified 
input file. The principal cause is a device hardware error. 


Suggested User Response: Reenter the command. 


I/O ERROR ON OUTPUT FILE <filename* 


Description: An error occurred while attempting to write into the named 
output file. The most likely causes are: 


Contiguous file cannot be extended. 
Device full. 


Device write-locked. 


me oe? oe ae 


Hardware error from device. 


Suggested User Response: Perform the appropriate corrective action and 
reenter the command. 


4.4.5 Errors in File Contents or Format 


The. following errors represent inconsistencies detected by PAT in the format 
or contents of input or correction files. 


ERROR IN FILE <filename> CHECKSUM 


Description: Checksum computed by PAT for the named file does not match 
that supplied by the user. 


Suggested User Response: Ensure that the correct checksum was specified. If 
the checksum was correct, either the input file or the correction file was 
incorrect. Rerun PAT and specify the correct file. 


FILE «filename» HAS ILLEGAL FORMAT 


Description: The format of the named file is not compatible with the object 
file format accepted by the Task Builder. The principal causes are: 
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1. Truncated input file. 


2. Input file consists of text. 


Suggested User Response: Ensure that the file is a compatible object file and 
resubmit it for PAT processing. 


INCOMPATIBLE REFERENCE TO GLOBAL SYMBOL «symbol name? 


Description: A correction file contains a global symbol whose attributes do not 
match any of the following input file symbol attributes: 


1. Definition or Reference. 


2. Relocatable or Absolute. 


Suggested User Response: Update the correction input file by modifying the 
symbol attributes. Reassemble the file and resubmit it for PAT processing. 


INCOMPATIBLE REFERENCE TO PROGRAM SECTION “section name? 


Description: A correction file contains a section name whose attributes do not 
match one of the input file section attributes: 


1. Relocatable or Absolute. 
2. .PSECT or .CSECT. 


Suggested User Response: Update the correction file by modifying the section 
attribute or changing the section type. Reassemble the file and resubmit it to 
PAT for processing. 


UNABLE TO LOCATE MODULE <module name> 
Description: A module name specified in the correction input file could not be 
found in the file of concatenated input modules. 


Suggested User Response: Update the correction file specification to include 
the missing module. Reenter the command line. 


UNABLE TO OPEN FILE 


Description: An error occurred trying to open a file to which you had no 
access. 


Suggested User Response: Use a privileged account or change the protection 
code of the file you are trying to access. 


4.4.6 Internal Software Error 


These errors reflect internal software error conditions. If they persist, submit a 
Software Performance Report along with the related console dialogue and any 
other pertinent information. 
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ILLEGAL ERROR-SEVERITY CODE <error data? 
Description: An error message call has been generated containing an illegal 
parameter. 


Suggested User Action: If the error persists, submit a Software Performance 
Report along with the related console dialogue and any other pertinent 
information. 


4.4.7 Storage Allocation Error 


The following error message indicates that insufficient task memory was 
available for storing global symbol and program section data: 


NO DYNAMIC STORAGE AVAILABLE “<storage-listhead® 
Description: Insufficient contiguous task memory was available to satisfy a 
request for the allocation of storage. 


<Storage-listhead> is a display of the two-word dynamic storage listhead 
contents in octal. 


Suggested User Response: None, this message is not relevent in RSTS/E. 
However if this message does appear, submit a Software Performance Report. 
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Chapter 5 
Using the MAKSIL Utility Program 


The MAKSIL utility program accepts as input files the generated output of 
the Task Builder, a task image file (extension .TSK) and a symbol table 
(extension.STB). Depending on how the program was originally coded and 
how you specify the MAKSIL utility program, MAKSIL produces a formatted 
output file that can be loaded into memory as a resident library (.LIB) or a 
run-time system (.RTS). 


When generating a run-time system, a new command file (.CMD) can also be 
generated. When generating either the .LIB or .RTS, you have the option of 
including the symbol table (.STB) into RSTS/E Save Image Library (SIL) 
format, thus allowing symbolic patching of the output file. 


5.1 Creating a Run-Time System (RTS) 


In order to use MAKSIL to format task builder output (task image) into a 
loadable run-time system, two conditions must be met. 


For the first condition: 


1. The starting address of the task image (the label referenced by the .END 
statement) must be within the lowest 1K of memory of the read-only 
portion of the task. 


2. The highest virtual address for the task must be 177774 (octal). The word 
at 177774 (octal) must contain a valid, non-zero maximum job image size 
entry. | 


The second condition requires the following step: 


1. Task-build the MACRO assembled run-time system code (.OBJ), then 
use MAKSIL to format the Task Builder output (.TSK and .STB). MAK- 
SIL will print the following error message if the .TSK file is not alligned 
properly: 


TASK MUST BE EXTENDED BY xxxxxxxx BYTES 


If the file is not properly aligned, edit the command file (.CMD) to extend 
a "dummy" control section by the required number of bytes to align the 
last .PSECT at the correct boundary and rerun MAKSIL. The "edit" 
mode of MAKSIL can be used to automatically modify the command file 
(see Section 5.2). 


MAKSIL may not work correctly if the Task Builder parameters are out of 
range. When you task build run-time system code, specify the following Task 
Builder options described in Table 5-1 to set the required virtual and physical 
address range. (See the RSTS/E Task Builder Reference Manual.) 


Table 5-1: Task Builder Options for Virtual and Physical Address 
Range 


Define virtual address base and range. PAR also implicitly specifies the largest 
| program (low-segment) area. 


The partition size is a multiple of 4K words. If the run-time system is only 


3K-words for example, the STACK option would be defined as "STACK=1024" 
to reserve an additional 1K-words. If this is done, the run-time system will 
occupy only 3K-words of physical memory when it is loaded. 


EXTSCT | RSTS/E requires the task to end at virtual address 177774. The EXTSCT option 
extends a control section (usually .99998) so that the vector control section 
(.99999) ends correctly. 


Table 5-2 defines the PAR and STACK options for various run-time system 
S1Zes. 


Table 5-2: Task Builder PAR and STACK Options for Various Sized 
Run-Time Systems 


a 
1K - 4K PAR=160000:020000* 
5K - 8K PAR=140000:040000 
9K - 12K PAR=120000:060000 
13K - 16K PAR=100000:100000 
17K - 20K PAR=060000: 120000 


21K - 24K 1 PAR=040000: 140000 
20K - 28K PAR=020000: 160000 


1K 5K 9K 138K 17K 21K 25K | STACK=3072 
2K 6K 10K 14K 18K 22K 26K} STACK=2048 
3K 7K 11K 15K 19K 23K 27K} STACK=1024 
4K 8K 12K 16K 20K 24K 28K} STACK=0000 


*PAR=virtual address:number of bytes 


The following example shows a control file for a dummy 4K word run-time 
system: 


FILE/-HD+FILE +FILE=FOOBLD/MP 
PAR=FILE:160000:020000 
STACK=0 

EXTSCT=.99998:000000 

// 
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After task building FILE.TSK and executing MAKSIL, the command file 
would be edited to change the PAR, STACK, and EXTSCT options to appro- 
priate values. The task builder is then rerun to correctly build the task. 


Finally, MAKSIL is rerun to build FILE.RTS. 


Run-time systems are built by first specifying the size (4K,8K,etc.) and then 
task building so as to include as many modules resident as will fit in the 
partition (leaving sufficient patch space). Then, MAKSIL is run to define the 
EXTSCT value. Finally, the extended task is built and converted to a run- 
time system. 


5.2 Creating a Resident Library 


MAKSIL can also produce a resident library output file. As shown in the 
example below, the switch /RTS is not appended to the filename entered in 
response to the first MAKSIL prompt. Note that the switch /DEBUG can be 
used if required. 


RUN $MAKSIL 

MAKSIL W70 RSTS/E Timesharing 

Resident Library name? TEST (Qe 

Task-built Resident Library input file =TEST.TSK?? TEST @eD 
Include symbol table (Yes/No) “Yes? Yes (Qe 

Symbol table input file <TEST.STB?? TEST @eD 

Resident Library output file <TEST.LIB:? TEST @e 

TEST built in 23 K-words» S48 symbols in the directory 
TEST. TSK renamed to TEST.TSK: 40:2 


Ready 


5.3 Operating Instructions 


Following are the keyboard operating commands and responses for MAKSIL. 


Type: 
RUN $MAKSIL 


After displaying its header line, MAKSIL prompts, and the user answers: 


Resident Library name’ FILE/RTS or FILE 


Type the name of the resident library (FILE, for example) or the run-time 
system name (FILE/RTS, as shown above). "RTS" is required if a run-time 
system is to be built. The switch /RTS signals that special conditions must be 
met by the .TSK file before proper conversion to a run-time system Save 
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Image Library (SIL) format can be made. When the switch /RTS is not used, 
MAKSIL assumes that a Resident Library file is to be created. The switch 
/DEBUG can be used when creating a run-time system or a resident library 
file to initiate printout of internal tables during the create process. 


MAKSIL then prompts: 


Task-built Resident Library input file “FILE.TSK=s? (er 
Or 
Task-built Run-Time System input file “FILE.TSK=s? (QE 


Type the name of the .TSK file, or press the RETURN key if the default name 
is acceptable. If a run-time system is to be built, the task is checked for 
correct parameters. If a resident library is requested, the next prompt is 
include symbol table. 


If in Build Mode, the program checks the format of the file as a run-time 
system and responds with either: 


The run-time system is correctly aligned 
or 
The run-time system is not aligned 


If in "Edit Mode", to redefine task-builder parameters. 

Edit mode (Yes/No) «Yes? 7 QE 

At this point, in running MAKSIL, you have two options; to enter the edit 
mode to redefine task build parameters, or the build mode to construct the 


run-time system. This option is presented by the following prompt: 


Task-builder command input file “FILE.CMD+? (Er 


If the run-time system is correctly alligned, the program will exit. 


The command file is edited to modify the EXTSCT, STACK and PAR op- 
tions to extend the task as necessary. The program then prompts: 


Corrected command filename <FILE.CMD+7 (QE 


If you respond with the RETURN key, the old file FILE.CMD will be re- 
named to FILE.BAK. The program then reminds you to rebuild the task and 
exits: 


Please task-build again using FILE.CMD 


If you answered "No" to the "Edit Mode" question, the program aborts if the 
task is not correctly aligned. Perform the task-build. If there are no problems, 
the following questions are asked: 


Include symbol table (Yes/No) “Yess? (er 
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Typing Yes and the RETURN key or just the RETURN key, will append a 
symbol table (.STB) to the run-time system. The .STB file allows you to 
patch the .RTS via INIT or the on-line patching mechanism. If a symbol table 
is requested, the prompt appears: 


Symbol table input file <FILE.STB27? QED 


Type the name of the .LIB or .RTS file, or the RETURN key if the default is 
acceptable. MAKSIL builds the run-time system or resident library (with 
symbol table if requested) into the output file and displays: 


Run-Time System output file <FILE.RTS:7 GED 
or 
Resident Library FILE.LIB @& 


Type the name of the .LIB or .RTS file, or the RETURN key if the default is 
acceptable. MAKSIL builds the run-time system or resident library (with 
symbol table if requested) into the output file and displays: 


FILE built in 4K wordss 123 symbols in the directory 


After the MAKSIL process, the task image file is renamed so that unprivi- 
leged users can access the task image with the "HISEG=" or the "LIBR=" 
switch when task building their programs. 


5.4 Messages 


There are three types of messages that can be encountered while using 
MAKSIL: 


1. Fatal error messages(?) 
2. Diagnostic messages(%) 


3. Informational messages 


These three types of messages, their causes, and user responses are described 
in the following sections. 


5.4.1 Fatal Error Messages 


TODD BASE OR TRANSFER ADDRESS 


Description: The .TSK file contains an incorrect transfer address or an odd 
value for a base address. 


Suggested User Response: Re-task build the program, and execute MAKSIL. 


TGARBAGE WHEN CONVERTING "nnnnn" IN "command" text 


Description: A conversion error has occurred. 


Using the MAKSIL Utility Program 5-5 


5-6 


Suggested User Response: Check the .CMD file, re-task build, and execute 
MAKSIL. 


PCOULDN’T FIND ALIGNMENT POINT 


Description: The alignment scan could not locate the communication vector. 
Suggested User Response: Check that the task build has been performed 
correctly. 


PARTITION OR STACK PARAMETER INCORRECT FOR TASK 


Description: You are trying to extend the task too far. 
Suggested User Response: Rebuild the task with correct "PAR=" and 
"STACK=" commands. 


?TASK IMAGE xxxxx.TSkK CANNOT BE CONVERTED TO RUN-TIME SYSTEM vrvyyr, 


Description: Same as message 


Suggested User Response: Check that the task is defined correctly. Common 
problems include a starting address that is not in the first 1K memory seg- 
ment, a missing vector control section (.99999), or overall incorrect run-time 
system design. Running MAKSIL using the /DEBUG switch on the 
"Run-Time System Name" question causes a list of internal symbols to be 
printed that can be helpful in determining the cause of the error. 


PERROR REOPENING SYMBOL TABLE 
Description: Opening the .STB file resulted in an error after the file had once 
successfully been opened. 


Suggested User Response: Re-execute the MAKSIL program. 
PERROR WHEN OPENING file.ext - - text 


Description: An error was encountered when opening the file "file.ext" de- 
scribed in error message "text". 


Suggested User Response: Type in correct filename in response to question. 
?DISK FILES ONLY» PLEASE 


Description: An attempt has been made to open a non-disk file for input or 
output operations. 


Suggested User Response: Enter only filenames that reside on the disk in 
response to MAKSIL questions. 
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TILLEGAL SYMBOL TABLE FORMAT 


Description: The symbol table (.ST'B) file does not have the file attributes of 
either formated binary or variable length records. 


Suggested User Response: Either an improper symbol table file has been 
specified, or the file has been corrupted. The program will build without the 
symbol table. Re-run the program with a valid symbol table file to include a 
symbol table. 


TERROR GETTING A .GSD ENTRY 


Description: In processing the symbol table (.ST'B) file, an error occurred that 
. prevents finding a valid symbol table entry. 


Suggested User Response: Either an improper symbol table file has been 
specified, or the file has been corrupted. The program will build without the 
symbol table. Re-run the program with a valid symbol table file to include a 
symbol table. 


PLONG FORMATTED-BINARY RECORD. 


Description: The symbol table (.STB) file contains a formatted binary record 
greater than 512 bytes. 


Suggested User Response: Either an improper symbol table file has been 
specified, or the file has been corrupted. The program will build without the 
symbol table. Re-run the program with a valid symbol table file to include a 
symbol table. 


PILLEGAL FORMATTED-BINARY RECORD 


Description: The symbol table (.STB) file contains a formatted record start- 
ing at an odd byte boundary. 


Suggested User Response: Either an improper symbol table file has been 
specified, or the file has been corrupted. The program will build without the 
symbol table. Re-run the program with a valid symbol table file to include a 
symbol table. 


TILLEGAL VYARTABLE-LENGTH RECORD 


Description: The symbol table (.STB) file contains a variable length record 
which either is greater than 512 bytes in length, or starts at an odd byte 
boundary. 


Suggested User Response: Either an improper symbol table file has been 
specified, or the file has been corrupted. The program will build without the 
symbol table. Re-run the program with a valid symbol table file to include a 
symbol table. 
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PTADDRESSING OUTSIDE OF TASK LIMITS 


Description: The program tried to access beyond the calculated end of the 
.TSK file. The task image is incorrect. 


Suggested User Response: Task build the program again and execute 
MAKSIL. 


TERROR GETTING BLOCK xx --text 


Description: A GET command was performed on block xx of the output file 
(.RTS or .LIB), which resulted in an error, as described in error message text. 


Suggested User Response: Execute the MAKSIL program again. 


TERROR PUTTING BLOCK xx -- text 


Description: A PUT command was performed on block xx of the output file, 
which resulted in an error, as described in the error message text. | 


Suggested User Response: Execute the MAKSIL program again. 


"ERROR GETTING FROM xxxx,.STB -- text 


Description: An error occurred when performing a GET command from the 
symbol table (.STB) file, as described in error message text. 


Suggested User Response: Re-execute the programs. 


TFATAL ERROR --text 


Description: An unexpected error has occurred. 


Suggested User Response: Send a Software Performance Report along with an 
appropriate listing of the error. 


5.4.2 Diagnostic Messages 


“RUN-TIME SYSTEM MAXIMUM JOB SIZE (xx) EXCEEDS CALCULATED MAXIMUM OF (y+) 


Description: The maximum size of a particular job (O.SIZE) as defined in the 
.TSK, is too great for the run-time system. For example, while assembling a 
run-time system requiring 16K words, a job size of 28K words had been 
defined. Since the run-time system and a job cannot exceed 32K words, the 
RSTS/E Monitor adjusts the maximum job size to 16K words. 


Suggested User Response: No response is required. 


AZMULTIPLE command: "first command" » "command line" 
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Description: A PAR, STACK, or EXTSCT command appears more than 
once. Only the first command, of a particular type, is used. 


Suggested User Response: No response is required. 


5.4.3 Informational Messages 


INCORRECT FILE SIZE xx» COMPUTED=ry 


Description: The actual file size is less than that calculated from parameters 
contained in the .TSK file. 


Suggested User Response: No response is required. 


THE RUN-TIME SYSTEM IS NOT ALIGNED 


or 


THE RUN-TIME SYSTEM IS CORRECTLY ALIGNED 


Description: One of the two messages above is displayed, depending on the 
outcome of the task verification phase. 


Suggested User Response: No response is required. 


THE COMMAND FILE IS ALREADY CORRECT.EXITING, 


Description: The edit mode was selected even though the task is correct. This 
may happen if MAKSIL is run from a batch stream 


Suggested User Response: No response is required. 


THE TASK- BUILDER COMMANDS HAVE BEEN CHANGED AS FOLLOWS 


OLD par NEW Par 
OLD stack NEW stack 
OLD extsct NEW extsct 


filename? will load in a xx K-words Partition wsing vy K-words 
Physical memory 

zz (octal) bytes may be used for expansion. 

Please task-build again using <filename?.CMD 


Description: The above message is displayed to log the edit mode changes. 


Suggested User Response: Re-task build using the edited command file. 


UTILITY ADD SUPPRESSED 


Description: This message is printed if the run-time system was not written to 
account [0,1). 


Suggested User Response: No response is required. 
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Appendix A 
MACRO-11 Diagnostic Error Message Summary 


A diagnostic error code is printed as the first character in a source line which 
contains an error detected by MACRO-11. This error code identifies a syntac- 
tical problem or some other type of error condition detected during the pro- 
cessing of a source line. An example of such a source line is shown below: 


Q 26 000236 010102 MOY RiyRZ+A 


The extraneous argument A in the MOV instruction above causes the line to 
be flagged with a Q (syntax) error. 


Error Code Meaning 


A Assembly error. Because many different types of error conditions produce this 
diagnostic message, all the possible directives which may yield a general assem- 
bly error have been categorized below to reflect specific classes of error condi- 
tions: 


CATEGORY 1: Tlegal Argument Specified. 
-RADIX -- A value other than 2, 8, or 10 is specified as a new radix. 


.LIST/.NLIST -- Other than a legally defined argument is specified with 
the directive. 


-ENABL/.DSABL -- Other than a legally defined argument is specified with 
the directive. 


.PSECT -- Other than a legally defined argument is specified with the 
directive. 


F/.IIF -- Other than a legally defined conditional test or an illegal argu- 
ment expression value is specified with the directive. 


-MACRO -- An illegal or duplicate symbol found in dummy argument list. 


CATEGORY 2: Null Argument or Symbol Specified. 


TITLE -- program name is not specified in the directive, or first non-blank 
character following the directive is a non-Radix-50 character. 


IRP/.IRPC -- No dummy argument is specified in the directive. 

.NARG/.NCHAR/.NTYPE —- No symbol is specified in the directive. 

IF/.J[F -- No conditional argument is specified in the directive. 
CATEGORY 3: Unmatched Delimiter/Illegal Argument Construction. 


/ASCU/.ASCIZ/.RAD50/.IDENT -- Character string or argument string del- 
imiters do not match, or an illegal character is used as a delimiter, or an 
illegal argument construction is used in the directive. 


.NCHAR -- Character string delimiters do not match, or an illegal character 
is used as a delimiter in the directive. 


CATEGORY 4: General Addressing Errors 


This type of error results from one of several possible conditions: 


1. Permissible range of a branch instruction. i.e., from -128 to +127 words, 
has been exceeded. 


2. A statement makes invalid use of the current location counter, e.g., a 
" =expression" statement attempts to force the current location counter 
to cross program section (.PSECT) boundaries. 


3. A statement contains an invalid address expression. In cases where an 
absolute address expression is required, specifying a global symbol, a 
relocatable value, or a complex relocatable value results in an invalid 
address expression. Similarly, in cases where a relocatable address ex- 
pression is required, either a relocatable or absolute value is permissible, 
but a global symbol or a complex relocatable value in the statement 
likewise results in an invalid address expression. Specific cases of this 
type of error are those which follow: : | 


.BLKB/.BLKW/.REPT -- Other than an absolute value or an expression 
which reduces to an absolute value has been specified with the directive. 


4. Multiple expressions are not separated by a comma. This condition 
causes the next symbol to be evaluated as part of the current expression. 


CATEGORY 5: Illegal Forward Reference. 


This type of error results from either of two possible conditions: 


1. A global assignment statement (symbol==expression) contains a for- 
ward reference to another symbol. 


2. An expression defining the value of the current location counter contains 
a forward reference. 


B Bounding error. Instructions or word data are being assembled at an odd address. 
The location counter is incremented by 1. 


D Doubly-defined symbol referenced. Reference was made to a symbol which is 
defined more than once. 
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End directive not found. When the end-of-file is reached during source input and 
the .END directive has not yet been encountered, MACRO-11 generates this 
error code, ends assembly pass 1, and proceeds with assembly pass 2. 


Illegal character detected. Illegal characters which are also non-printable are 
replaced by a question mark (?) on the listing. The character is then ignored. 


Input line is greater than 132 characters in length. Currently, this error condition 
is caused only through excessive substitution of real arguments for dummy argu- 
ments during the expansion of a macro. 


Multiple definition of a label. A label was encountered which was equivalent (in 
the first six characters) to a label previously encountered. 


A number contains a digit that is not in the current program radix. The number is 
evaluated as a decimal value. 


Opcode error. Directive out of context. Permissible nesting level depth for condi- 
tional assemblies has been exceeded. Attempt to expand a macro which was 
unidentified after .MCALL search. 


Phase error. A label’s definition of value varies from one assembly pass to another 
or a multiple definition of a local symbol has occurred within a local symbol 
block. Also, when in a local symbol block defined by the .EKNABL LSB directive, 
an attempt has occurred to define a local symbol in a program section other than 
that which was in effect when the block was entered. A P error code also appears 
if an .ERROR directive is assembled. 


Questionable syntax. Arguments are missing, too many arguments are specified, 
or the instruction scan was not completed. 


Register-type error. An invalid use of or reference to a register has been made, or 
an attempt has been made to redefine a standard register symbol without first 
issuing the .DSABL REG directive. 


Truncation error. A number generated more than 16 bits in a word, or an expres- 
sion generated more than 8 significant bits during the use of the BYTE directive 
or trap (EMT or TRAP) instruction. 


Undefined symbol. An undefined symbol was encountered during the evaluation 
of an expression; such an undefined symbol is assigned a value of zero. Other 
possible conditions which result in this error code include unsatisfied macro 
names in the list of LMCALL arguments and a direct assignment (symbol=expres- 
sion) statement which contains a forward reference to a symbol whose definition 
also contains a forward reference; also, a local symbol may have been referenced 
that does not exist in the current local symbol block. 


Instruction error. The instruction so flagged is not compatible among all members 
of the PDP-11 family. 
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Appendix B 
Librarian Utility Program (LBR) Files and Formats 


A library file consists of a library header, an entry point table, a module name 
table, the library modules, and (usually) free space. The entry point table has 
zero length for macro libraries. See Figure B-1. 


B.1 Library Header 


The header section is a full block (256 words) in which the first 23 words are 
used to describe the current status of the library. Its contents are updated as 
the library is modified, so LBR can access the information it needs to perform 
its functions (Insert, Compress, etc.) See Figure B-2. 


B.2 Entry Point Table 


The entry point table consists of 4-word elements that contain an entry point 
name (words 0-1), and a pointer to the module header where the entry point is 
defined (words 2-3). See Figure B-3. This table is searched when a library 
module is referenced by one of its entry points. The table is sequenced in order 
of ascending entry point names. The entry point table is not used for macro 
library files. 


B.3 Module Name Table 


The module name table is searched when the library module is referenced by 
its module name, rather than by one of its entry points. It is comprised of 
4-word elements; a module name (words 0-1) and a pointer to the module 
header (words 2-3). See Figure B-4. The module name table is sequenced in 
order of ascending module names. 


B.4 Module Header 


Each module starts with an 8-word header, identifying the type and status 
(normal and deleted) of the module, its length (number of words), etc. (see 
Figure B-5). 


For object modules, the low-order bit of the attributes byte is set if the module 
has the selective search attribute. (See Section 3.3.11 "Selective Search 
Switch (/SS)." The selective search attribute reduces task build time.) Also, 
for object modules, the 2 words of type-dependent information contain the 
module identification defined by the .IDENT directive at assembly time. For 
macro modules, these 2 fields are undefined. 


Figure B-1: Standard Library File Format 
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Figure B-2: Contents of Library Header 


OFFSET 


WORD NON ZERO ID LIBRARY TYPE 


LBR (LIBRARIAN) VERSION 


(.IDENT FORMAT) 


DATE AND 

TIME OF LAST 

INSERT HOUR 
MINUTE 
SECOND 


NO. EPT ENTRIES AVAILABLE 
RESERVED SIZE MNT ENTR’S 


MNT STARTING REL BLOCK 
NO. MNT ENTRIES ALLOCATED 
NO. MNT ENTRIES AVAILABLE 


LOGICALLY DELETED 
AVAILABLE (BYTES) 
CONTIGUOUS SPACE 
AVAILABLE (BYTES) 
NEXT INSERT RELATIVE BLOCK 


START BYTE WITHIN BLOCK 
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Figure B-3: Format of Entry Point Table Element 


WORD 


0 GLOBAL SYMBOL 
1 NAME (RADS50) 


y) ADDRESS OF RELATIVE BLK. 
MODULE 


3 | HEADER _ BYTE IN BLOCK 


Figure B-4: Format of Module Name Table Element 


WORD 


0 MODULE NAME 


1 (RADS5O) 


2 ADDRESS OF RELATIVE BLK. 


MODULE 


3 HEADER BYTE IN BLOCK 


Figure B-5: Module Header Format 
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ATTRIBUTES STATUS 


O=NORMAL MODULE 
1=DELETED MODULE 
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Where more than one page number appears for an entry, the defining entry is in bold type. 
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Make Save Image Library, 1-4t 
operating instructions, 5-3, 5-4 
use of, 5-1 

MC argument, 2-4t 

MD argument, 2-4t 

ME argument, 2-4t 

MEB argument, 2-4t 

Messages 
command line errors, 4-10 
diagnostic errors, A-1 
fatal errors and library files, 3-20 
file content errors, 4-13 
file format errors, 4-13, 4-14 
file specification errors, 4-11 
I/O errors, 4-12, 4-13 
information, 4-9, 4-10 
internal software errors, 4-14 
LBR error, 3-21 to 3-28 
for MACRO-11 errors, 2-6 to 2-9 
MAKSIL diagnostic messages, 5-8 
MAKSIL fatal errors, 5-5 to 5-7 


MAKSIL informational messages, 5-9 


with MAKSIL, 5-5 

PAT errors, 4-9 

storage allocation error, 4-15 
Messages, with MAKSIL 

diagnostic, 5-8 


Messages, with MAKSIL (cont.) 
fatal error, 5-5 to 5-8 
informational, 5-9 

Modules 
adding a subroutine to, 4-7 
header, described, B-2 
header, format, B-4f 
name table, described, B-2 
name table, format, B-4f 
object, updated with PAT, 4-6 


object, updated with Task Builder, 4-6 


overlaying lines in, 4-6 
updating with PAT, 4-2f 


updating with PAT, processing steps, 4-3f 


Object modules 
patch utility, 4-1 
updated with PAT, 4-6 
updated with Task Builder, 4-6 
Operating instructions 
for MAKSIL, 5-3, 5-4 
Output library file, 3-14t to 3-16t 
Overlaying lines in a module, 4-6 


PAR option 
Task Builder, 5-2t 


for various sized run-time systems, 5-2t 


PAT command line, 4-4 
checksum switch, 4-4 
specifying, 4-4 

PAT utility 
application of updates, 4-4 
correction file, 4-5 
error messages, 4-9 
information messages, 4-9, 4-10 
input file, 4-4 
to invoke, 1-4, 4-2 
messages, list of, 4-9 
specifying command lines, 44 
updating a module, 4-2f, 4-3f 
updating object modules, 4-6 
use of, 4-1, 4-2 


Patch Object Module, CCL name, 1-4t 


Physical address range 

Task Builder option, 5-2t 
PNC argument, 2-5t 
PSECT 

in PAT command line, 4-5 


REG argument, 2-5t 
Replace switch, 3-2t 
example, 3-14, 3-15 


Index-3 


Replace switch, (cont.) 
format, global, 3-138 to 3-15 
format, local, 3-13, 3-15 
use of, 3-12, 3-13 
Resident library 
creation of, 5-3, 5-4 
RSX-based utilities, CCL names for, 1-4t 
RUN command 
entering, 1-4 
Run-time systems (RTS) 
to create, 5-1 
PAR and STACK options, 5-2t 


Selective Search switch, 3-2t, 3-16 
SEQ argument, 2-4t 
Software errors, internal, 4-14 
Squeeze switch, 3-2t, 3-17 
format, global, 3-17 
format, local, 3-17 
MACRO listing of, 3-18f 
rules for, 3-18 © 
SRC argument, 2-4t 
STACK option 
Task Builder, 5-2t 
for various sized run-time systems, 5-2t 
Standard library file format, B-2f 
STB, symbol table, 5-5 
Storage allocation error, 4-15 
Subroutines, added to a module, 4-7 
Switches | 
arguments for /DS and /EN, 2-5t 
arguments for /LI and /NL, 2-4t 
assembly pass, 2-6 
Checksum, 4-8, 4-9 
Compress, 3-2t, 3-3 
Create, 3-2t, 3-4 
Default, 3-2t, 3-6, 3-7 
Delete, 3-2t, 3-5 
Delete Global, 3-2t, 3-7, 3-8 
Entry Point, 3-2t, 3-8, 3-9 
Extract, 3-2t, 3-9, 3-10 
function control, 2-5 
Insert, 3-2t, 3-10, 3-11 
LBR, 3-2t 


Index-4 


Switches, (cont.) 
List, 3-2t, 3-11, 3-12 
MACRO-11, 2-3, 2—4t 
MACRO-11 library file, 2-6 
Replace, 3-2t, 3-12 to 3-15 
Selective Search, 3-2t, 3-16 
Squeeze, 3-2t 
Squeeze, global format, 3-17 
Squeeze, local format, 3-17 

SYM argument, 2-4t 

Symbol table, appended to run-time system, 
5-5 


Tables 
entry point, B-1 
entry point element format, B-4f 
module name, B-2 
symbol, appended to run-time system, 5-5 
Task Builder 
options, PAR and STACK, 5-2t 
options, physical address range, 5-2t 
options, virtual address range, 5-2t 
processing files, 4-7 
updating object modules, 4-6 
TOC argument, 2-4t 
TTM argument, 2-4t 


Utilities 
accessing, 1-3 
command lines, entering, 1-4 
command lines, format, 1-1 
command lines,,entering, 1-5 
entering command lines, 1-4, 1-5 
LBR, files and formats, B-1 
Librarian, 1-4, 3-1, B-1 
MACRO-11, 2-1 
MACRO-11 program, 2-1 
MAKSIL, 1-4, 5-1 
PAT, 1-4, 4-1 | 
RSX-based, CCL names, 1-4 


Virtual address range 
Task Builder option, 5-2t 
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